如何在OpenAPI中引用响应组件？

Question

我正在为我的 API 编写 OpenAPI 定义。我正在使用components响应，但当我尝试引用这些组件时，Swagger Editor 显示错误：

responses:
  - $ref: '#/components/responses/401'
  - $ref: '#/components/responses/400'

引用响应组件的正确方法是什么？

Answer 1

引用响应组件的正确方法是：

responses:
  '400':
    $ref: '#/components/responses/400'
  '401':
    $ref: '#/components/responses/401'

也就是说，它responses是一个映射（不是数组/列表），其中键是 HTTP 状态代码，值是响应定义。

引用组件时可以覆盖响应描述吗？

这在 OpenAPI 3.1 中是可行的，但在早期版本中则不然。将新的description放在$ref：

# openapi: 3.1.0

responses:

  '400':
    $ref: '#/components/responses/400'
    description: This description overrides that of the referenced response.

  '401':
    $ref: '#/components/responses/401'
    description: This description overrides that of the referenced response.