How to reference headers in response

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.

[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).