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

Question

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

Answer 1

根据第2.3节“{3}}的回复标题”，答案是否定的。这也是我从2.0规范中理解的。

对Writing OpenAPI (Swagger) Specification Tutorial – Part 5 – Advanced Input And Output Modeling投票/评论。

Answer 2

这在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