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

Question

Is it possible to declare a custom response header which would be present in all responses without copying it in each of the response structure?

Answer 1

This was somewhat improved in OpenAPI 3.0 – you can now can define common headers in the global components/headers section and then $ref these definitions instead of repeating the inline definitions. You can also $ref whole responses (e.g. 400) to reduce the code duplication a bit. However, there's still no way to set common headers for all paths – you'll need to list the headers explicitly in each response.

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

According to section 2.3 Response’s headers of Writing OpenAPI (Swagger) Specification Tutorial – Part 5 – Advanced Input And Output Modeling the answer is no. Which is what I understand from the 2.0 spec too.

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