OpenAPI如何通过$ref为响应示例数组配置多个引用元素

OpenAPI生态工具的默认生成逻辑为：当数组items仅关联单个Schema引用时，工具只会取该Schema下配置的单条example，生成仅含1个元素的数组示例。要实现多元素、甚至跨Schema引用的数组示例，按以下方式配置即可：

场景1：数组元素均为同一Schema结构（对应3个预报项的目标效果） #

不需要修改原有Schema定义，直接在payload数组节点下新增example字段，显式声明完整的数组示例内容即可，原有$ref引用会继续承担结构校验的作用：

responses:
        '200':
          description: json containing the updated notification
          content:
            application/json:
              schema:
                type: object
                properties:
                  payload:
                    type: array
                    items:
                      $ref: "#/components/schemas/forecast_item"
                    # 数组层级显式配置示例，会覆盖工具自动生成的单元素示例
                    example:
                      - transmission_date: "2022-06-08 12:00:00"
                        timestamp: 1654689600
                        temperature: 28.28
                        humidity: 33
                        rain: 0
                        icon: "04d"
                      - transmission_date: "2022-06-08 13:00:00"
                        timestamp: 1654693200
                        temperature: 29.1
                        humidity: 30
                        rain: 0
                        icon: "02d"
                      - transmission_date: "2022-06-08 14:00:00"
                        timestamp: 1654696800
                        temperature: 30.5
                        humidity: 28
                        rain: 0
                        icon: "01d"

配置完成后渲染出的示例就会包含指定数量、结构符合forecast_item定义的数组元素，你也可以根据需要调整元素数量、每个元素的具体字段值。

场景2：数组元素来自不同Schema引用 #

如果数组需要承载多种类型的项，先通过anyOf/oneOf声明允许的Schema引用范围，再同样在数组层级配置example即可，示例里可以直接写不同结构的元素，也可以引用其他Schema下预定义的示例：

payload:
  type: array
  items:
    anyOf:
      - $ref: "#/components/schemas/forecast_item"
      - $ref: "#/components/schemas/forecast_warning_item"
      - $ref: "#/components/schemas/forecast_alert_item"
  example:
    # 普通预报项示例
    - transmission_date: "2022-06-08 12:00:00"
      timestamp: 1654689600
      temperature: 28.28
      humidity: 33
      rain: 0
      icon: "04d"
    # 预警类型项示例
    - transmission_date: "2022-06-08 12:30:00"
      warning_level: "blue"
      warning_type: "thunderstorm"
    # 告警类型项示例
    - alert_id: "a20220608001"
      expire_time: 1654700400
      content: "短时强降水预警"

注意事项 #

• 不要在单个item的Schema里配置数组格式的example，工具不会自动把它拆成多元素数组，只会把整个数组当成单个item的值渲染
• 数组层级配置的example优先级高于Schema内部定义的单条example，所有主流OpenAPI渲染工具（Swagger UI、Redoc、Stoplight Elements等）都支持该配置规则

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