0

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.

Helen
  • 87,344
  • 17
  • 243
  • 314
  • Does this answer your question -- [How can I represent 'Authorization: Bearer ' in a Swagger Spec (swagger.json)](https://stackoverflow.com/q/32910065/113116)? To recap: you need to use the `securityDefinitions` section (instead of `components/securitySchemes`) and define the `Authorization` header as an API key. – Helen Nov 15 '22 at 20:42

0 Answers0