OpenAPI中如何正确引用components下的response响应组件？

你当前的写法不符合OpenAPI规范要求，错误原因是：paths节点下单个接口的responses字段必须是以HTTP状态码为键的映射对象，不支持直接传入数组格式的引用。

正确的引用方式如下：

responses:
  # 键为对应的HTTP状态码，值关联你提前定义好的响应组件
  400:
    $ref: '#/components/responses/400'
  401:
    $ref: '#/components/responses/401'
  # 补充接口正常返回的状态码定义，示例：
  200:
    description: 请求成功
    content:
      application/json:
        schema:
          type: object
          # 后续补充你的业务返回结构即可

如果你需要在多个接口批量复用通用的错误响应定义，也可以直接把通用响应集合抽成组件，在对应接口直接引用整个响应映射，示例：

# components里先定义通用响应集合
components:
  responses:
    CommonErrorResponses:
      400:
        $ref: '#/components/responses/400'
      401:
        $ref: '#/components/responses/401'
      403:
        $ref: '#/components/responses/403'
      404:
        $ref: '#/components/responses/404'

# 接口处直接引用
paths:
  /your/api/path:
    get:
      responses:
        $ref: '#/components/responses/CommonErrorResponses'
        # 再补充当前接口特有的响应，比如200
        200:
          description: 成功返回

内容的提问来源于stack exchange，提问作者Vinh Nguyễn