Openapi-specification: How to reference headers in response

[john1452]

I am trying to figure out a way to reuse headers in response. The documentation and google isn't helping much. I am wondering if this is even possible to include headers inside response using $ref.

My response is defined as below. In the successful response my Api returns pagination information in headers.
This pagination headers are used in many places, I want to reuse them so that i don't duplicate lot of YAML code.

Following is my attempt at trying this without any luck.

responses:
        '200':
          description: Successful Request
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
          headers:
                 - $ref: '#/components/headers/X-Total-Items'
                 - $ref: '#/components/headers/X-Total-Pages'

components
headers:
    X-Total-Items
      schema:
        type: integer
        description: test
  X-Total-Pages
      schema:
        type: integer
        description: test

Is this the right way?

[MikeRalphson]

Hi @john1452 the thing to spot is that the headers field of the Response Object is a Map (of Header objects or References), not an array.

Your example should look something like:

openapi: 3.0.1
info:
  title: API
  version: 1.0.0
paths:
  /:
    get:
      responses:
        '200':
          description: Successful Request
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
          headers:
            'X-Total-Items':
               $ref: '#/components/headers/xTotalItems'
            'X-Total-Pages':
               $ref: '#/components/headers/xTotalPages'
components:
  schemas:
    User: {}
  headers:
    xTotalItems:
      schema:
        type: integer
        description: test
    xTotalPages:
      schema:
        type: integer
        description: test

I have modified the names of the reusable header components to indicate clearly which is used as the actual header name, though they can of course be the same.

[john1452]

Hi @MikeRalphson

Thanks for quick response.
This does work. However the description isn't displayed next to the Header in swagger ui.
Example: https://app.swaggerhub.com/apis/SoftInc/kkk/1.0.0#/default/post_users

sounds like a bug to me. Should I report this on swagger ui repo?

[MikeRalphson]

Sorry, didn't spot that. The header object has a description field of its own. Try moving the descriptions out of the schema objects (i.e. one level up).

[MikeRalphson]

Looks like we can close this?

[pmonty]

Hey guys, have added the changes as @MikeRalphson has advised and my typescript-fetch sdk is not adding the headers when I look at the api.ts generated :(

Headers section (at bottom of file)

  headers:
    xTotalCount:
      schema:
        type: integer

Added it to the response

responses:
   "200":
      description: OK
         content:
            application/json:
               schema:
                   type: array
                      items:
                         $ref: "#/components/schemas/LearncycleItem"
         headers:
             'X-Total-Count':
                $ref: '#/components/headers/xTotalCount'

EDIT:
Have been following https://swagger.io/docs/specification/describing-responses/ but still nothing have attempted a number of variations

• with and without quotation marks
• no headers objects in component and defining the type in the response
• ordering of content and headers section (even adding description to the headers etc...)

I am sure the changes are valid as it generates and if I change a different path somewhere else and rename it the change is in the newly generated sdk

This is the command I am running
java -jar openapi-generator-cli.jar generate -i my-api.yml -l typescript-fetch -o typescript-fetch-client-koru-api --additional-properties modelPropertyNaming=original --skip-validate-spec