OpenAPI 3.x如何引用统一响应集合避免重复编写响应配置？

核心结论 #

你期望的直接将整个responses节点引用一个自定义响应组的用法，在OpenAPI 3.0和3.1版本中均不被官方规范支持。OpenAPI规范要求responses对象必须是键为HTTP状态码/default的映射结构，不能直接在responses根节点使用$ref指向一个响应集合。

可行的替代方案 #

方案1：使用YAML原生的锚点+合并键（兼容性最优） #

这是最推荐的方案，完全基于YAML语法特性，不需要依赖OpenAPI规范升级，也不需要修改工具链，还支持灵活覆盖特定状态码的配置，正好适配你提到的delete接口200响应和其他接口不同的场景。

示例写法：

# 提前定义共用响应的锚点，可放在文件任意顶层位置
x-common-response-templates:
  location-install-base: &location-install-base-responses
    400:
      $ref: '#/components/responses/BadRequestResponse'
    404:
      $ref: '#/components/responses/NoComponentResponse'
    default:
      $ref: '#/components/responses/UnknownErrorResponse'

# 接口定义部分
/api/maint/locations/{locationID}:
  parameters:
    - $ref: '#/components/parameters/LocationID'
  post:
    operationId: installComponent
    # 其他字段省略...
    responses:
      <<: *location-install-base-responses # 引用共用响应
      200: # 单独定义当前接口特有的200响应
        $ref: '#/components/responses/SuccessResponse'
  put:
    operationId: refreshInstalledComponent
    # 其他字段省略...
    responses:
      <<: *location-install-base-responses
      200:
        $ref: '#/components/responses/SuccessResponse'
  delete:
    operationId: uninstallComponent
    # 其他字段省略...
    responses:
      <<: *location-install-base-responses
      200: # 单独覆盖delete的200响应即可
        $ref: '#/components/responses/ComponentResponse'

方案2：使用OpenAPI扩展自定义响应组 #

如果你的工具链（文档生成、代码生成等）支持自定义扩展，可以自己定义x-responses-group扩展字段实现整组复用。这种方式需要你的工具链做适配，适合内部工具链完全可控的场景。

方案3：保持单响应引用（完全符合规范） #

如果不想用YAML特性也不想做扩展，也可以继续使用现有单响应$ref的写法，虽然比整组复用多几行代码，但已经比全量复制响应配置精简很多，且100%符合OpenAPI规范，所有工具都原生支持。

关于oneOf的说明 #

oneOf是OpenAPI中用于Schema定义的关键字，用来描述单个响应体可能的多种结构，不能用来定义多个不同状态码的响应集合，所以这个方向无法实现你的需求。

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