如何在OpenAPI中复用重复响应状态码代码块及扩展？

问题描述 #

我的文档里反复出现这段重复的响应码引用代码块：

responses:
    '204':
      $ref: '#/components/responses/204'
    '400':
      $ref: '#/components/responses/400'
    '401':
      $ref: '#/components/responses/401'
    '402':
      $ref: '#/components/responses/402'
    '403':
      $ref: '#/components/responses/403'
    '404': 
      $ref: '#/components/responses/404'
    '426':
      $ref: '#/components/responses/426'
    '429':
      $ref: '#/components/responses/429'

想知道怎么通过OpenAPI把它改成仅一行引用，就像这样：

responses:
    $ref: '#/components/responses/defaultCodes'

另外，能不能用allOf扩展这个状态码列表，比如这样：

responses:
    allOf:
    - '200':
      $ref: '#/components/responses/200'
    - $ref: '#/components/responses/defaultCodes'

解答 #

1. 实现一行引用复用响应码 #

要实现这个需求，只需先把重复的响应码集合封装到components/responses中，之后直接引用即可：

步骤1：在Components中定义复用集合

在OpenAPI文档的components区域，新增一个responses条目，将你需要复用的响应码集合封装进去：

components:
  responses:
    # 定义可复用的默认响应码集合
    defaultCodes:
      '204':
        $ref: '#/components/responses/204'
      '400':
        $ref: '#/components/responses/400'
      '401':
        $ref: '#/components/responses/401'
      '402':
        $ref: '#/components/responses/402'
      '403':
        $ref: '#/components/responses/403'
      '404': 
        $ref: '#/components/responses/404'
      '426':
        $ref: '#/components/responses/426'
      '429':
        $ref: '#/components/responses/429'

步骤2：在接口中引用该集合

之后在任意需要使用这套响应码的接口里，直接通过$ref引用defaultCodes即可：

paths:
  /your-api-endpoint:
    get:
      summary: 示例接口
      responses:
        $ref: '#/components/responses/defaultCodes'

2. 关于用allOf扩展响应码列表 #

OpenAPI规范不支持在responses字段下使用allOf。

allOf关键字仅适用于合并Schema结构（比如请求体、响应体的字段定义），但对于responses这种以状态码为键的对象，规范没有提供合并语法支持。

如果需要扩展默认响应码集合，可采用以下两种替代方案：

• 方案1：直接在接口中追加状态码
  在引用defaultCodes的同时，直接新增需要的状态码即可。如果默认集合中已有相同状态码，接口中定义的会覆盖默认值：

  responses:
    $ref: '#/components/responses/defaultCodes'
    '200':
      $ref: '#/components/responses/200'
  

• 方案2：定义新的复用集合
  若需要多次使用“默认集合+新增状态码”的组合，可在components/responses中单独定义一个新集合：

  components:
    responses:
      defaultWith200:
        '200':
          $ref: '#/components/responses/200'
        '204':
          $ref: '#/components/responses/204'
        '400':
          $ref: '#/components/responses/400'
        # 复制defaultCodes中的其他响应码
  

  之后直接引用defaultWith200即可。

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