OpenAPI如何通过$ref在响应示例数组中添加多个条目

你的写法不生效是OpenAPI规范本身的限制：$ref 仅能用于Schema结构定义的位置，example 字段存放的是最终输出的字面量示例值，不会解析任何引用语法。你在数组内写的$ref会被识别为普通的对象键名，自然无法生成预期的多元素数组示例。
另外你贴的试写配置还有个笔误：你实际定义的Schema名称是forecast_item，配置里写的引用路径指向device，就算支持示例内引用也会因为路径匹配失败无法渲染。

你不需要在示例里重复写引用，Schema层已经通过items.$ref约束了数组元素的结构，只需要在对应位置提供具体的示例值即可，有两种常用写法：

写法1：媒体类型层级定义完整响应示例（兼容性最好，支持所有OpenAPI渲染工具） #

将example和schema同级配置，直接写完整的响应结构，配置如下：

responses:
        '200':
          description: 返回预报数据列表
          content:
            application/json:
              schema:
                type: object
                properties:
                  payload:
                    type: array
                    items:
                      $ref: "#/components/schemas/forecast_item"
              # 注意example和schema是平级，不要写到properties内部
              example:
                payload:
                  - 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:00:00"
                    timestamp: 1654689600
                    temperature: 28.28
                    humidity: 33
                    rain: 0
                    icon: "04d"
                  - transmission_date: "2022-06-08 12:00:00"
                    timestamp: 1654689600
                    temperature: 28.28
                    humidity: 33
                    rain: 0
                    icon: "04d"

上面的配置渲染出来的结果和你预期的效果完全一致。如果需要更贴近真实场景，也可以给不同数组元素设置不同的字段值。

写法2：数组属性层级定义示例（OpenAPI 3.x 原生支持） #

如果不想写完整的外层对象结构，也可以直接给payload数组属性配置example，把多个元素直接写在数组值里：

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 12:00:00"
                        timestamp: 1654689600
                        temperature: 28.28
                        humidity: 33
                        rain: 0
                        icon: "04d"
                      - transmission_date: "2022-06-08 12:00:00"
                        timestamp: 1654689600
                        temperature: 28.28
                        humidity: 33
                        rain: 0
                        icon: "04d"

• 所有example/examples字段内都不支持使用$ref引用，必须填写实际的字面量值
• 如果使用Swagger UI、Redoc等常见的OpenAPI渲染工具，上面两种写法都可以正常生成多元素数组的响应示例

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