How to define header parameters in OpenAPI 3.0?

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: []
      ...

Leave a Comment