How to define header parameters in OpenAPI 3.0?

Question

In OpenAPI (Swagger) 2.0, we could define header parameters like so:

paths:
  /post:
    post:
      parameters:
        - in: header
          name: X-username

But in OpenAPI 3.0.0, parameters are replaced by request bodies, and I cannot find a way to define header parameters, which would further be used for authentication.

What is the correct way to define request headers in OpenAPI 3.0.0?

Answer 1

In OpenAPI 3.0, header parameters are defined in the same way as in OpenAPI 2.0, except the type has been replaced with schema:

paths:
  /post:
    post:
      parameters:
        - in: header
          name: X-username
          schema:
            type: string

When in doubt, check out the Describing Parameters guide.

But in Swagger 3.0.0 parameters are replaced by request bodies.

This is only true for form and body parameters. Other parameter types (path, query, header) are still defined as parameters.

define header parameters, which would further be used for authentication.

A better way to define authentication-related parameters is to use securitySchemes rather than define these parameters explicitly in parameters. Security schemes are used for parameters such as API keys, app ID/secret, etc. In your case:

components:
  securitySchemes:
    usernameHeader:
      type: apiKey
      in: header
      name: X-Username

paths:
  /post:
    post:
      security:
        - usernameHeader: []
      ...