OpenAPI中是否可定义可复用响应集合通过$ref统一引用？

首先明确结论：你期望的「在responses节点下与200/201等成功响应同级，直接通过$ref引入整个公共错误响应集合」的写法不符合OpenAPI原生规范，无法通过官方schema校验。原因是OpenAPI规定responses对象的键只能是HTTP状态码（支持2XX/4XX这类范围通配符）或default兜底字段，$ref不能作为同级键直接使用。

你要实现「一次定义公共错误集合、后续新增公共错误无需逐个修改接口配置」的需求，可以用以下兼容原生规范、主流工具全支持的写法：

通用方案：allOf合并公共响应片段（OpenAPI 3.0+ 全版本支持） #

1. 先在components/responses下定义独立的公共错误响应集合，以及每个错误码对应的具体响应结构

components:
  responses:
    # 单个错误响应定义，后续也可单独在特殊接口复用
    401UnauthorizedDefault:
      description: 未授权，请先完成身份认证
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommonError'
    404NotFound:
      description: 请求的资源不存在
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommonError'
    502BadGatewayDefault:
      description: 网关服务异常
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommonError'
    # 聚合所有公共错误的集合，后续新增公共错误只需要修改这一处
    AllCommonErrorResponses:
      401:
        $ref: '#/components/responses/401UnauthorizedDefault'
      404:
        $ref: '#/components/responses/404NotFound'
      502:
        $ref: '#/components/responses/502BadGatewayDefault'
  schemas:
    CommonError:
      type: object
      properties:
        code:
          type: integer
        message:
          type: string

2. 每个接口的responses节点通过allOf，合并当前接口的专属响应（比如成功响应）和公共错误集合

paths:
  /home:
    get:
      summary: 获取首页数据
      responses:
        allOf:
          - 200:
              description: 操作成功
              content:
                application/json:
                  schema:
                    $ref: '#/components/schemas/HomeData'
          - $ref: '#/components/responses/AllCommonErrorResponses'
  /sign_up:
    post:
      summary: 用户注册
      responses:
        allOf:
          - 201:
              description: 注册成功
              content:
                application/json:
                  schema:
                    $ref: '#/components/schemas/UserInfo'
          - $ref: '#/components/responses/AllCommonErrorResponses'

方案说明 #

• 该写法完全兼容OpenAPI 3.x系列规范，Swagger UI、Redoc、OpenAPI Generator等主流生态工具都能正常解析渲染
• 后续需要新增公共错误响应（比如429请求限流、500服务内部错误），只需要在AllCommonErrorResponses节点下追加对应的错误码配置即可，所有引用该集合的接口会自动同步新的错误响应，无需逐个修改接口配置
• 如果你的工具链支持OpenAPI扩展（比如Redocly、Speccy等文档工具），还可以配置全局响应注入规则，连接口处的allOf引用都不需要写，工具会自动给所有接口追加公共错误响应，该能力属于工具扩展，不属于原生规范范畴。

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