Swagger / Open API 2.0 我可以声明一个共同的响应 header 吗？

Question

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

Answer 1

根据 Writing OpenAPI (Swagger) Specification Tutorial – Part 5 – Advanced Input And Output Modeling 的第 2.3 部分回复的 headers，答案是否定的。这也是我从 2.0 规范中了解到的。

Vote/comment Structural improvements: enhance headers handling · Issue #690 · OAI/OpenAPI-Specification。

Answer 2

这在 OpenAPI 3.0 中有所改进 – 您现在可以在全局 components/headers 部分定义通用 headers，然后 $ref 这些定义，而不是重复内联定义。您还可以 $ref 整个响应（例如 400）以减少代码重复。但是，仍然存在 no way to set common headers for all paths – 您需要在每个响应中明确列出 headers。

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

Swagger / Open API 2.0 我可以声明一个共同的响应 header 吗？

Swagger / Open API 2.0 can I declare a common response header?

openapi

swagger-2.0