How to define custom headers in OpenAPI 2.0 (Swagger 2.0)?

Question

I'm having problems defining custom request headers for my OpenAPI (Swagger) document. I've looked in the documentation https://swagger.io/docs/specification/describing-parameters/#header-parameters but I cannot get it to work.

In my example below is a POST request which has has a body. I also want it to have a custom header like my second snippet, but that is not valid.

This is OK:

 /search:
    post:
      tags:
        - Domain
      summary: Search for domains
      description: Returns a domain if it was found.
      produces:
        - application/json
      parameters:
        - in: body
          name: body
          description: Array of Domain Names
          required: true
          schema:
            $ref: '#/definitions/DomainNames'

This is not OK:

  /search:
    post:
      tags:
        - Domain
      summary: Search for domains
      description: Returns a domain if it was found.
      produces:
        - application/json
      parameters:
       - in: header
          name: X-Request-ID
          schema:
            type: string
            format: uuid
          required: true
        - in: body
          name: body
          description: Array of Domain Names
          required: true
          schema:
            $ref: '#/definitions/DomainNames'

On the - in: header line I get the following error:

Schema error at paths['/search'].post.parameters[0].in
should be equal to one of the allowed values
allowedValues: body, header, formData, query, path
Jump to line 37

Schema error at paths['/search'].post.parameters[0]
should NOT have additional properties
additionalProperty: schema, in, name
Jump to line 37

What am I missing here? The header shows up in the rendered Swagger UI but I can't "Save" it as it is not valid.

Helen Helen · Accepted Answer · 2019-04-18T08:54:17

The guide you linked to is for OpenAPI 3.0 (as indicated at the top of that page). The corresponding OpenAPI 2.0 guide is here: Describing Parameters.

In OpenAPI 2.0, path/header/query/form parameters do not use schema, they use the type keyword directly.

Also, the - in: header line in your example is not indented enough, you need to add one more space before it to align it with other lines.

Here's the correct version:

      parameters:
        - in: header     # <----
          name: X-Request-ID
          type: string   # <----
          format: uuid   # <----
          required: true

How to define custom headers in OpenAPI 2.0 (Swagger 2.0)?

1 Answers