Swagger header definitions

Question

I can't seem to find if it is possible to declare a header object in order to reuse it in response headers, there are examples defining objects for response schemas, but it doesn't transpose to response headers. I have only managed to make a reusable response object like this:

responses:
  DownloadOk:
    description: Dowload Ok
    headers:
      Content-Length:
        description: response length
        type: integer 
      Document-Length:
        description: document length
        type: integer 

But as I said, I'd like to keep the header part only.

Here is where I would like to use it:

responses:
    200:
      description: Dowload Ok
      headers:
        $ref: '#/definitions/DowloadOk'

Answer 1

According to Swagger/OpenAPI spec you can't. Definitions must contain Schema Objects, and those do not allow arbitrary properties, but specific subset of JSON Schema (see the link).

You were able to define a Response Object and reference that, because the Swagger Object has global responses property. No such thing for headers. Not at this time, anyway. It could be worth to request such feature.

Answer 2

I have faced the same issue. In the document they declare;

Note that, currently, OpenAPI Specification does not permit to define common response headers for different response codes or different API operations. You need to define the headers for each response individually.

see the Response Header section at Describing Responses .