多文件引用OpenAPI中字典嵌套示例无法渲染的问题咨询

针对OpenAPI拆分文件后，嵌套字典示例无法渲染、字段重复显示的问题，最稳妥的解决方式是把示例从末端的DataContainer.yaml移到引用它的字段上（即CreateParams.yaml里的data字段），具体调整如下：

修改后的文件内容 #

CreateParams.yml #

type: object
properties:
  name:
    type: string
    description: The default name
  data:
    $ref: './DataContainer.yaml'
    description: 存储嵌套键值对的容器
    example:
      -1:
        0: 100000
        1: 200000
        2: 300000
        3: 400000
      0:
        0: 100000
        1: 200000
        2: 300000
        3: 400000

DataContainer.yml #

type: object
additionalProperties:
  type: object
  additionalProperties:
    type: number
description: 内部为数字键映射数值集合的嵌套结构
# 移除原有的example，避免渲染冲突

为什么这样有效 #

1. 渲染工具兼容性：多数OpenAPI渲染工具（如Swagger UI、Redoc）对跨文件引用的schema中定义的example支持有限，尤其是additionalProperties这类动态结构，工具无法正确将末端schema的示例关联到上层字段。把示例放在直接引用的字段上，工具会直接识别为当前字段的示例，正常渲染嵌套结构。
2. 解决重复显示问题：字段重复是因为工具同时解析了引用目标schema的描述/字段，以及当前字段的配置，将示例和描述集中在引用字段层级，可避免重复解析导致的异常。

如果需要在DataContainer中保留示例（用于其他复用场景），可以使用x-example扩展字段（部分工具支持），但优先推荐上述方案保证渲染兼容性。

内容的提问来源于stack exchange，提问作者Iosiv