How can I represent 'Authorization: Bearer <token>' in a Swagger Spec (swagger.json)
SwaggerSwagger 2.0Swagger EditorSwagger Problem Overview
I am trying to convey that the authentication/security scheme requires setting a header as follows:
Authorization: Bearer <token>
This is what I have based on the swagger documentation:
securityDefinitions:
APIKey:
type: apiKey
name: Authorization
in: header
security:
- APIKey: []
Swagger Solutions
Solution 1 - Swagger
Maybe this can help:
swagger: '2.0'
info:
version: 1.0.0
title: Based on "Basic Auth Example"
description: >
An example for how to use Auth with Swagger.
host: basic-auth-server.herokuapp.com
schemes:
- http
- https
securityDefinitions:
Bearer:
type: apiKey
name: Authorization
in: header
paths:
/:
get:
security:
- Bearer: []
responses:
'200':
description: 'Will send `Authenticated`'
'403':
description: 'You do not have necessary permissions for the resource'
You can copy&paste it out here: http://editor.swagger.io/#/ to check out the results.
There are also several examples in the swagger editor web with more complex security configurations which could help you.
Solution 2 - Swagger
Bearer authentication in OpenAPI 3.0.0
OpenAPI 3.0 now supports Bearer/JWT authentication natively. It's defined like this:
openapi: 3.0.0
...
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT # optional, for documentation purposes only
security:
- bearerAuth: []
This is supported in Swagger UI 3.4.0+ and Swagger Editor 3.1.12+ (again, for OpenAPI 3.0 specs only!).
UI will display the "Authorize" button, which you can click and enter the bearer token (just the token itself, without the "Bearer " prefix). After that, "try it out" requests will be sent with the Authorization: Bearer xxxxxx
header.
Authorization
header programmatically (Swagger UI 3.x)
Adding If you use Swagger UI and, for some reason, need to add the Authorization
header programmatically instead of having the users click "Authorize" and enter the token, you can use the requestInterceptor
. This solution is for Swagger UI 3.x; UI 2.x used a different technique.
// index.html
const ui = SwaggerUIBundle({
url: "http://your.server.com/swagger.json",
...
requestInterceptor: (req) => {
req.headers.Authorization = "Bearer xxxxxxx"
return req
}
})
Solution 3 - Swagger
Posting 2022 answer in JSON using openapi 3.0.0:
{
"openapi": "3.0.0",
...
"servers": [
{
"url": "/"
}
],
...
"paths": {
"/skills": {
"put": {
"security": [
{
"bearerAuth": []
}
],
...
},
"components": {
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT"
}
}
}
}
Solution 4 - Swagger
Why "Accepted Answer" works... but it wasn't enough for me
This works in the specification. At least swagger-tools
(version 0.10.1) validates it as a valid.
But if you are using other tools like swagger-codegen
(version 2.1.6) you will find some difficulties, even if the client generated contains the Authentication definition, like this:
this.authentications = {
'Bearer': {type: 'apiKey', 'in': 'header', name: 'Authorization'}
};
There is no way to pass the token into the header before method(endpoint) is called. Look into this function signature:
this.rootGet = function(callback) { ... }
This means that, I only pass the callback (in other cases query parameters, etc) without a token, which leads to a incorrect build of the request to server.
My alternative
Unfortunately, it's not "pretty" but it works until I get JWT Tokens support on Swagger.
Note: which is being discussed in
- security: add support for Authorization header with Bearer authentication scheme #583
- Extensibility of security definitions? #460
So, it's handle authentication like a standard header. On path
object append an header paremeter:
swagger: '2.0'
info:
version: 1.0.0
title: Based on "Basic Auth Example"
description: >
An example for how to use Auth with Swagger.
host: localhost
schemes:
- http
- https
paths:
/:
get:
parameters:
-
name: authorization
in: header
type: string
required: true
responses:
'200':
description: 'Will send `Authenticated`'
'403':
description: 'You do not have necessary permissions for the resource'
This will generate a client with a new parameter on method signature:
this.rootGet = function(authorization, callback) {
// ...
var headerParams = {
'authorization': authorization
};
// ...
}
To use this method in the right way, just pass the "full string"
// 'token' and 'cb' comes from elsewhere
var header = 'Bearer ' + token;
sdk.rootGet(header, cb);
And works.
Solution 5 - Swagger
By using requestInterceptor, it worked for me:
const ui = SwaggerUIBundle({
...
requestInterceptor: (req) => {
req.headers.Authorization = "Bearer " + req.headers.Authorization;
return req;
},
...
});
Solution 6 - Swagger
My Hackie way to solve this was by modifying the swagger.go file in the echo-swagger package in my case:
At the bottom of the file update the window.onload function to include a requestInterceptor which correctly formats the token.
window.onload = function() {
// Build a system
const ui = SwaggerUIBundle({
url: "{{.URL}}",
dom_id: '#swagger-ui',
validatorUrl: null,
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIStandalonePreset
],
plugins: [
SwaggerUIBundle.plugins.DownloadUrl
,
layout: "StandaloneLayout",
requestInterceptor: (req) => {
req.headers.Authorization = "Bearer " + req.headers.Authorization
return req
}
})
window.ui = ui
}
Solution 7 - Swagger
Solving this from laravel 7x ("openapi": "3.0.0"), edit your config\l5-swagger.php with the following codes
'securityDefinitions' => [
'securitySchemes' => [
'bearerAuth' => [
'type' => 'http',
'scheme' => 'bearer',
'bearerFormat' => 'JWT',
],
],
then you can add this as a security annotation for your endpoint:
*security={
*{
*"bearerAuth": {}},
*},