Use Authorization Header with Swagger

Recently, on a project I had to document an API using Swagger, as an authentication mechanism, the API, is using JWT.

The Token needs to be set in the Authorization Header of the HTTP request as this :

Authorization Bearer: JWT-token

As we wanted to use the Swagger UI to allow clients to test requests and responses of the API.

To define the API, we use the Swagger Editor Online.

Start the Documentation and the /login route

First we need to create the main API description :

swagger: '2.0'
info:
 version: 0.0.1
 title: MY-SUPERB-API
host: '127.0.0.1:4000'
schemes:
 - http
 - https
produces:
 - application/json
paths:
 /login:
  post:
   tags:
    - auth
   description: |
    Allow users to log in, and to receive a Token
   parameters:
    -
     in: body
     name: body
     description: The email/password
     required: true
     schema:
      $ref: '#/definitions/Login'
   responses:
    '200':
     description: Login Success
     schema:
      $ref: '#/definitions/Token'
    '400':
     description: Whether the user is not found or error while login
     schema:
      $ref: '#/definitions/Error'
    '403':
     description: >-
      If user is not found (bad credentials) OR if user can not login (a
      concierge of an unsctive client)
     schema:
      $ref: '#/definitions/Error'
definitions:
 Login:
  type: object
  properties:
   email:
    type: string
   password:
    type: string
 Token:
  type: object
  properties:
   token:
    type: string
 Error:
  type: object
  properties:
   message:
    type: string
   error:
    type: string

This will define the /login route that receive a POST HTTP request with email and password, if they matches your credential provider the route will return a Token response :

{
  "token":"JWT TOKEN"
}

Describe the Security Definition

Now we should define create a securityDefinitions, this will describe how authorization is made, and allow the Swagger UI to ask for a token when needed.

So first edit the API definition :

swagger: '2.0'
info:
 version: 0.0.1
 title: MY-SUPERB-API
host: '127.0.0.1:4000'
schemes:
 - http
 - https
produces:
 - application/json
securityDefinitions: (1)
 Bearer:
  description: |
   For accessing the API a valid JWT token must be passed in all the queries in
   the 'Authorization' header.


   A valid JWT token is generated by the API and retourned as answer of a call
   to the route /login giving a valid user & password.


   The following syntax must be used in the 'Authorization' header :

       Bearer: xxxxxx.yyyyyyy.zzzzzz
  type: apiKey
  name: Authorization
  in: header
paths:
 /login:
  post:
   tags:
    - auth
   description: |
    Allow users to log in, and to receive a Token
   parameters:
    -
     in: body
     name: body
     description: The email/password
     required: true
     schema:
      $ref: '#/definitions/Login'
   responses:
    '200':
     description: Login Success
     schema:
      $ref: '#/definitions/Token'
    '400':
     description: Whether the user is not found or error while login
     schema:
      $ref: '#/definitions/Error'
    '403':
     description: >-
      If user is not found (bad credentials) OR if user can not login (a
      concierge of an unsctive client)
     schema:
      $ref: '#/definitions/Error'
definitions:
 Login:
  type: object
  properties:
   email:
    type: string
   password:
    type: string
 Token:
  type: object
  properties:
   token:
    type: string
 Error:
  type: object
  properties:
   message:
    type: string
   error:
    type: string

1	Ajout de la clé securityDefinitions

The description is, I think, self described, so you can understand it

Create a protected route

And now you can define a route /users for example that needs the user to send a valid Authorization header …

swagger: '2.0'
info:
 version: 0.0.1
 title: MY-SUPERB-API
host: '127.0.0.1:4000'
schemes:
 - http
 - https
produces:
 - application/json
securityDefinitions:
 Bearer:
  description: |
   For accessing the API a valid JWT token must be passed in all the queries in
   the 'Authorization' header.


   A valid JWT token is generated by the API and retourned as answer of a call
   to the route /login giving a valid user & password.


   The following syntax must be used in the 'Authorization' header :

       Bearer: xxxxxx.yyyyyyy.zzzzzz
  type: apiKey
  name: Authorization
  in: header
paths:
 /login:
  post:
   tags:
    - auth
   description: |
    Allow users to log in, and to receive a Token
   parameters:
    -
     in: body
     name: body
     description: The email/password
     required: true
     schema:
      $ref: '#/definitions/Login'
   responses:
    '200':
     description: Login Success
     schema:
      $ref: '#/definitions/Token'
    '400':
     description: Whether the user is not found or error while login
     schema:
      $ref: '#/definitions/Error'
    '403':
     description: >-
      If user is not found (bad credentials) OR if user can not login (a
      concierge of an unsctive client)
     schema:
      $ref: '#/definitions/Error'
 /users:
  get:
   tags:
    - users
   security:
    - Bearer: []
   description: Get a list of all existing users
   responses:
    '200':
     description: An array of users
     schema:
      type: array
      items:
       $ref: '#/definitions/User'
definitions:
 Login:
  type: object
  properties:
   email:
    type: string
   password:
    type: string
 Token:
  type: object
  properties:
   token:
    type: string
 Error:
  type: object
  properties:
   message:
    type: string
   error:
    type: string
 User:
    type: object
    properties:
     email:
      type: string
     password:
      type: string
     firstName:
      type: string
     lastName:
      type: string
     lastLogin:
      type: string
      format: date

Now you just described that the /users route need the Bearer authentication …