openapi - Swagger / Open API 2.0 我可以声明一个公共响应头吗？

Question

是否可以声明一个自定义响应标头，该标头将出现在所有响应中，而无需在每个响应结构中复制它？

Answer 1

这在 OpenAPI 3.0 中有所改进——您现在可以在全局components/headers部分定义公共标头，然后$ref定义这些定义，而不是重复内联定义。您还可以$ref整体响应（例如 400）以减少代码重复。但是，仍然没有办法为所有路径设置公共标头——您需要在每个响应中明确列出标头。

openapi: 3.0.1
...
paths:
  /:
    get:
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
  /something:
    get:
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'

components:
  headers:
    X-RateLimit-Limit:
      description: Request limit per hour
      schema:
        type: integer
      example: 100
    X-RateLimit-Remaining:
      schema:
        type: integer
      example: 96

Answer 2

根据编写 OpenAPI (Swagger) 规范教程 - 第 5 部分 - 高级输入和输出建模的响应标题部分，答案是否定的。这也是我从 2.0 规范中所理解的。

对结构改进进行投票/评论：增强标头处理·问题 #690·OAI/OpenAPI-规范。