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

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.

Answer 1

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