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?

Helen · Accepted Answer · 2018-05-01 14:07:13Z

68

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

edited May 1, 2018 at 14:07

answered May 1, 2018 at 13:53

Helen

99.8k17 gold badges280 silver badges352 bronze badges

Sign up to request clarification or add additional context in comments.

5 Comments

kritika agarwal Over a year ago

But this API is to send the username and password to a third party for authenticating the login and in return sends the token ID which I would further use in bearer authentication value for other APIs, would that still be a good idea to add in component?

Helen Over a year ago

It's up to you really. I would define Bearer auth as a security scheme but the initial login request with regular parameters.

kritika agarwal Over a year ago

That's what I did and yes it worked for me, thanks Helen, instant help appreciated..

Rodrigo Gomez-Palacio Over a year ago

I need to pass in something like Usage-Data: kind=sdk, name=nodejs, version=1.2.3 via the header. This never changes and I want it to be sent on all requests for all paths. How can I do this? @Helen

Helen Over a year ago

@RodrigoGomez-Palacio please ask a new question.

Collectives™ on Stack Overflow

How to define header parameters in OpenAPI 3.0?

1 Answer 1

5 Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

5 Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related