2

I followed the following link from swagger documentation to create swagger json for my rest api.

https://swagger.io/docs/specification/2-0/describing-request-body/

In my rest api, I have request body and http headers like Content-Type and Authorization that go along with the service request.

I was wondering if there is a way to include request body and http header information in the swagger json ? I don't see that information in the swagger docs.

Hary
  • 1,127
  • 4
  • 24
  • 51

1 Answers1

0

The Content-Type header of requests and responses is defined by the consumes and produces keywords, respectively. They can be specified on the operation level or on the root level of the spec.

The Authorization header is defined using the securityDefinitions and security keywords. OpenAPI/Swagger 2.0 supports Basic authentication, API keys and OAuth 2.

Other headers can be defined as in: header parameters.

For example, if an operation POSTs JSON and uses Basic auth, you can describe it as follows:

swagger: '2.0'
...

securityDefinitions:   # Authorization, part 1
  basicAuth:
    type: basic

paths:
  /something:
    post:
      summary: POST some JSON
      consumes:
        - application/json  # Request Content-Type
      produces:
        - application/json  # Response Content-Type
      security:
        - basicAuth: []     # Authorization, part 2
      parameters:
        - in: body
          name: body
          required: true
          schema:
            $ref: '#/definitions/Something'
      responses:
        200:
          description: OK

Relevant documentation:
MIME Types
Authentication
Describing Parameters

Helen
  • 87,344
  • 17
  • 243
  • 314
  • Is there a way to specify Authorization header with bearer token in swagger spec 2.0 ? – Hary Nov 14 '17 at 21:24
  • @Hary: Assuming you mean standalone bearer tokens (not as part of OAuth 2 flow) - in 2.0 you would define it as an [API key](https://swagger.io/docs/specification/2-0/authentication/api-keys/), and the word `Bearer ` is considered part of the key value. The latest version, OpenAPI 3.0, supports Bearer auth natively. See [this question](https://stackoverflow.com/q/32910065/113116) for details. – Helen Nov 14 '17 at 21:34