Openapi-specification: Reference Response headers Open API v3.0

[pyromanci]

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!

[pyromanci]

Oh it's a Map. For what ever reason the Map in the type column in specs just didn't register in my brain.

Possibly in a future revision the headers for the requests could be an array. would be nicer to have to do 1 line per header instead of 2.

[bolshoydi]

@hkosova You said >>>"Note that you can only $ref individual headers but not the entire headers section."
and how to $ref (link) to the whole section like security section can? (like this)[https://swagger.io/docs/specification/authentication/oauth2/] you can Apply the security globally to all operations, but i want to apply respnse headers to all the operations avoiding copy-paste.

[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

[n-alex-white]

@hkosova I see that some of those feature requests have been around for three years. Excuse my ignorance of how the process works, but how long does it typically take for feature requests to be considered? Any idea whether these are active or dead? Thanks.