Use Authorization Header with Swagger
Recently, on a project I had to document an API using http://swagger.io/[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 http://swagger.io/swagger-ui/[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:
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
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 …
Use Swagger UI
In order to use the Swagger UI, you should be aware that the host value is defined on ‘127.0.0.1:4000’ and this may be changed in your case !
First Login and get the token
The now you can use the Swagger UI (with the editor) to login :
And the response should be :
Authenticate the editor :
Now at the top of the generated documentation you can click the Authenticate Button :
Then fill with the Token you received at the previous step :
NOTE: We are spcifying the Bearer: keyword.
Try the protected route
Now in the section of the protected route : /users
you can check the Bearer checkbox and try the operation :
You should have a valid answer :
Now you can add your other routes to finish defined your API.
Have fun !