Sending additional headers

[faustbrian]

I am currently using Swagger UI 3.1.6 and can't figure out how to set additional headers that will be send on every request.

Is there some way I can set additional headers in the swagger.json or even add inputs to the UI where the developer can set the value of those custom headers directly through Swagger UI configuration?

[faustbrian]

Is this repetitive way the only way to handle this?

parameters:
  customHeader1:
    name: custom
    in: header
    type: string
  customHeader2:
    name: custom
    in: header
    type: string
  customHeader3:
    name: custom
    in: header
    type: string

paths:
  "/api":
    get:
      tags:
      - ''
      summary: ''
      operationId: ''
      parameters:
      - $ref: '#/parameters/customHeader1' # Repeat the $refs on every possible request, very repetitive
      - $ref: '#/parameters/customHeader2'
      - $ref: '#/parameters/customHeader3'
      - in: query
        type: string
        name: q
        description: ''
        required: true
      responses:
        '200':
          description: ''
          schema: {}

[shockey]

We do have a request interceptor option1... but that's for programmatic modification of outgoing requests, not defining custom data at request runtime via the UI.

I'm not quite sure what you're trying to achieve here, though. Having customHeader defined more than once is invalid YAML, and using the parameter more than once in one operation is against the Swagger/OpenAPI specification (each parameter in an operation must have a unique name + in combination).

What are you trying to handle by defining custom headers? If you share some more information, we may be able to point you in the right direction.

[faustbrian]

I updated the snippet above as it was just meant to clarify that I have multiple custom headers that are required to be send which each and every request.

I have like 40 paths defined and everytime I have to add the 3x $ref for the custom headers at the top.

What I want to know is if there is a way to specify that these headers need to be send with every request and how to display inputs for these headers somewhere on the top of the page. Is it even possible to have global parameters for every request that render inputs somewhere on the page like they do for path parameters?

[hkosova]

@faustbrian, what kind of headers are these?

If they are API keys, you can describe them using the securityDefinitions and security keywords instead. Then they will apply globally.

If they are generic headers like X-RequestId, User-Agent, etc, you'll need to $ref them in all requests, because OpenAPI 2.0/3.0 do not have a concept of global parameters. You can $ref them on the path level instead of inside operations to reduce the code duplication:

paths:
  /something:
    # Path-level parameters, inherited by all operations with that path
    parameters:
      - $ref: '#/parameters/customHeader1'
      - $ref: '#/parameters/customHeader2'
      - $ref: '#/parameters/customHeader3'
  
    get:
      ...
    post:
      ...
    patch:
      ...

There are existing feature requests for global parameter and parameter groups in the OpenAPI Specification repository:
Group multiple parameter definitions for better maintainability
Global/common parameters

[faustbrian]

Yeah I know about the securityDefinitions and security keywords but they are generic headers that are required by the server to know about a few things which is why I am currently doing the $ref part in every single request.

Guess I will keep doing that till OpenAPI has support for global or grouped parameters to clean things up, just seems overly repetitive. Thanks!

[hkosova]

@faustbrian, there is a workaround using YAML anchors, as shown here. Instead of repeating all the $refs you'll need to repeat the anchor name only. This works in Swagger Editor/UI.

# &-anchors must be defined BEFORE they are *-referenced!

x-globalParameters: &GLOB_PARAMS
  - $ref: '#/parameters/customHeader1'
  - $ref: '#/parameters/customHeader2'
  - $ref: '#/parameters/customHeader3'

paths:
  /something:
    parameters: *GLOB_PARAMS
      
    get:
      parameters:
        - in: query
          type: string
          name: q
          description: ''
          required: true
      ...
    post:
      ...

  /another_path:
    parameters: *GLOB_PARAMS
    get:
      ...
    post:
      ...

[faustbrian]

Thanks, I will give it a shot.