能否在OpenAPI中为数据库文档查询请求定义两种成功响应结构？

问题背景 #

文档查询接口根据数据库返回结果，可能返回两种响应：多条文档时返回列表结构，单条文档时返回详情结构，想知道两种设计思路是否可行：

1. 用200状态码返回列表响应，201状态码返回详情响应
2. 在200响应内定义两种子类型结构分别对应列表和详情

方案一：用200/201区分响应类型（不可行） #

HTTP状态码有明确的语义规范，201 Created专门用于表示资源创建成功的场景，完全不适合查询类接口的响应。无论查询返回单条还是多条数据，只要查询成功，都应该用200 OK作为状态码。用201会让接口调用方产生误解，也不符合REST接口的设计规范，所以这个方案不建议采用。

方案二：在200响应内定义两种子类型（可行） #

OpenAPI支持通过oneOf关键字在单个响应中定义多种可能的schema结构，完美适配这种“二选一”的响应场景。具体实现可以参考以下示例：

responses:
  '200':
    description: 查询成功，返回文档列表或单条文档详情
    content:
      application/json:
        schema:
          oneOf:
            - $ref: '#/components/schemas/DocumentList'
            - $ref: '#/components/schemas/DocumentDetail'
          # 可选：添加鉴别器帮助调用方快速区分响应类型
          discriminator:
            propertyName: type
            mapping:
              list: '#/components/schemas/DocumentList'
              detail: '#/components/schemas/DocumentDetail'

components:
  schemas:
    DocumentList:
      type: object
      properties:
        type:
          type: string
          enum: [list]
        total:
          type: integer
          description: 文档总数
        items:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              title:
                type: string
    DocumentDetail:
      type: object
      properties:
        type:
          type: string
          enum: [detail]
        id:
          type: string
        title:
          type: string
        content:
          type: string
          description: 文档详细内容
        createTime:
          type: string
          format: date-time

补充说明 #

• oneOf关键字表示响应会严格匹配其中一个schema结构，避免出现歧义。
• 可选的discriminator（鉴别器）通过指定一个固定字段（比如示例中的type），让接口调用方可以直接根据该字段的值判断返回的是列表还是详情，降低解析成本。如果不使用鉴别器，调用方也可以通过检查字段（比如是否存在items或content）来判断响应类型。

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