如何在OpenAPI中正确定义返回Activity对象列表的响应？

你犯了一个典型的OpenAPI引用路径错误：你引用的#/components/responses/Activity是完整的响应对象定义（包含状态码、响应描述、内容结构等），而非Activity的数据模型schema。OpenAPI对非schema类型的引用会默认解析为string类型，所以最终生成了["string"]的错误结构。

修复步骤： #

1. 将Activity数据模型移到components/schemas下
   确保你的Activity对象结构定义在components/schemas节点（这是OpenAPI存放数据模型的标准位置），示例：

   components:
     schemas:
       Activity:
         type: object
         properties:
           id:
             type: integer
             description: 活动ID
           title:
             type: string
             description: 活动标题
           start_time:
             type: string
             format: date-time
             description: 活动开始时间
           # 按需添加其他属性
   

2. 修正响应中的引用路径
   在200响应的array schema的items里，引用#/components/schemas/Activity，而非responses下的路径。正确的接口响应定义示例：

   paths:
     /api/activities:
       get:
         summary: 获取活动列表
         responses:
           '200':
             description: 成功返回活动列表
             content:
               application/json:
                 schema:
                   type: array
                   items:
                     $ref: '#/components/schemas/Activity'
   

额外说明 #

如果之前你误将Activity的schema放在了components/responses里，一定要把它迁移到schemas节点——responses节点的作用是定义完整的HTTP响应（含状态码、描述、头部等），不是用来存放单个数据模型的。

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