Multiple specifications for the header with the same name in components

Hello!

According to the specification header object (in components section) must not include a name, the name is derived from the headers map’s key instead.

But, what if I want to have multiple header specifications for the header with the same name?

For example, I can have different API endpoints (or groups of endpoints) which require different authentication parameters:

openapi: 3.0.1

info:
  version: 0.0.0
  title: Some Title
  description: Some description

paths:
  /foo/:
    post:
      parameters:
        - name: Authorization
          in: header
          schema:
            type: string
            minLength: 32
            maxLength: 64
            
      responses:
        200:
          description: Some description
          
  /bar/:
    post:
      parameters:
        - name: Authorization
          in: header
          required: true
          schema:
            type: string
            minLength: 128
            maxLength: 128
            
      responses:
        200:
          description: Some description

How do I extract those headers to components section and reference them with $ref?

I can do it this way, and actually swagger UI understand that and renders correctly:

openapi: 3.0.1

info:
  version: 0.0.0
  title: Some Title
  description: Some description

paths:
  /foo/:
    post:
      parameters:
        - $ref: '#/components/headers/auth1'
            
      responses:
        200:
          description: Some description
          
  /bar/:
    post:
      parameters:
        - $ref: '#/components/headers/auth2'
            
      responses:
        200:
          description: Some description

components:
  headers:
    auth1:
      name: Authorization
      schema:
        type: string
        minLength: 32
        maxLength: 64
    auth2:
      name: Authorization
      required: true
      schema:
        type: string
        minLength: 128
        maxLength: 128

But, it throws validation errors, because I’m using name property for headers specified in the components/headers section.

Also, if name is not referenced in the header specification, the Swagger UI doesn’t display header’s name at all (look like it doesn’t know how to derive it from the headers map’s key), but it’s another issue with the Swagger itself, but it could also be a sign of a more major problem.

Could someone elaborate on this? Thank you!

[handrews]

@darrelmiller the problem comes when trying to specify what links will or may be present. If you are making heavy use of the Link header as your hypermedia strategy, you need to be able to indicate what rel values are present in responses, preferably without imposing an order on them. If one is forced to treat the value as a single string (comma-separated for multiple link values since the object format makes it impossible to specify each value separately), then you are in trouble. Regular expressions are not expressive for such cases.

[hibaymj]

@handrews I concur that regex is not really up to the task of parsing multiple link headers with any associated semantics. Like @darrelmiller showed, I think it’s really a case where some custom parsing is required.

The thinking I had for multiple Links to be returned within a current OAS document was to define a schema which would describe the network and system semantics of the potential response, the ordering, the range of rel values, if a rel is required, while leaving domain semantics out of scope. This schema would then use the alternate schema functionality in #1532.

@darrelmiller wrote:

Having the same HTTP header name with two different set of rules seems like an unwise thing to do. It certainly isn’t how standard HTTP headers are defined.

I think this is related to the fact that there are some headers which are defined with strict bounds, and others like Link or Prefer which have some characteristics of a collector or container. I make the suggestion above, because to include multiple versions of a header in the same scope would likely present a difficult challenge for the tooling ecosystem and would require time to work through. While, alternate schema would at least provide a sufficient stopgap until the root spec could evolve.