Reference Response headers Open API v3.0

I’ve been experimenting trying to break my large file into smaller and easier to handle files. I may be completely miss understanding part of the documentation where it says Headers can be a reference object.

But how come this doesn’t validate in the 3.0.

 /Account:
    parameters:
    - $ref: #/components/parameters/userAgent
    - $ref: #/components/parameters/installationID
    get:
      tags:
      - Account
      summary: Gets a list of Accounts
      description: Returns a list containing all Accounts. The list supports paging.
      operationId: listAccounts
      responses:
        200:
          description: A list of AchAccount
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/Accounts'
          headers:
            $ref: #/components/responses/DefaultHeaders/headers
        500:
          $ref: #/components/responses/StandardErrorResponse
        default:
          $ref: #/components/responses/TotallyUnexpectedResponse
      parameters:
      - $ref: #/components/parameters/offline_filter
      - $ref: #/components/parameters/limit_filter
      - $ref: #/components/parameters/page_filter

[hkosova]

headers is a map of header names to response header definitions (aka Header Objects). The “value” of a header name can be an inline definition, or a $ref to a definition stored elsewhere (either in the current file or an external file). Within the current OpenAPI document, response headers can be stored in the #/components/headers section.

Note that you can only $ref individual headers but not the entire headers section.

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'

components:
  headers:
    X-RateLimit-Limit:
      description: Request limit per hour
      schema:
        type: integer
      example: 100
    X-RateLimit-Remaining:
      schema:
        type: integer
      example: 94

Hope this helps!

[hkosova]

@bolshoydi you can’t, you can only $ref individual response headers - as shown in the example. However, there are existing feature requests to improve header reuse: Share header with multiple response objects Structural improvements: enhance headers handling