I am learning to use Swagger to document my API, and everything was well-explained until I got to the authentication portion. To give you some context of my API's authentication: it uses passport-jwt to authenticate users, sends an access token in the response body, and sets a refresh token in an httpOnly cookie. This is the swagger.json documentation I have so far:
{
"swagger": "2.0",
"info": {
"title": "API",
"description": "Coin-based API",
"version": "1.0.0"
},
"host": "localhost:4000",
"schemes": ["http"],
"consumes": ["application/json"],
"produces": ["application/json"],
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"in": "header",
"bearerFormat": "JWT"
}
}
},
"paths": {
"/api/users/transfer": {
"patch": {
"summary": "Transfer coins from one user to another",
"description": "Transfers coins from one user to another",
"security": [
{
"bearerAuth": []
}
],
"parameters": [
{
"name": "body",
"in": "body",
"schema": {
"type": "object",
"properties": {
"amount": {
"example": "any"
},
"recipient": {
"example": "any"
}
}
}
}
],
"responses": {
"200": {
"description": "Returns the user's new balance"
},
"400": {
"description": "Cannot transfer to yourself and/or Amount must be greater than 0"
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Insufficient funds"
},
"404": {
"description": "User not found"
}
}
}
},
I couldn't find a good reference on what the best practices are to let the client know that he needs to send a access token in the header. Right now on my swagger Ui, I see a an open lock and no information about the authorization process. What should I do?
I expect the client to see the information about the authorization process and able to send a request with an access token.