Swagger v2.0 JSON spec for Authorization Bearer
Today in this article, we shall see an example of Swagger JSON OpenApi 2.0 spec for Authorization Bearer representing Authorization bearer within OpenAPI( Swagger V2.0) specification.
Today in this article, we will cover below aspects,
Bearer authentication is an HTTP authentication scheme where the client must send the security tokens called bearer tokens within the Authorization header when making requests to restricted resources.
Authorization: Bearer <token>Understanding Global Vs Operation level security scheme
- Global Authentication scheme
Global authentication scheme gets applied to all REST API within API/Controllers and can be executed on all API decorated. That means every API with a secured header needs to provide a secured header before accessing restricted resources.
- Operation-level Authentication scheme
Operation level authentication scheme gets applied to on specific REST API within API/Controllers.
Swagger JSON V2.0 spec -Global Scope
Below is a sample example for Swagger JSON V2.0 spec, which details how to represents the details for global level security scheme
{
"swagger": "2.0",
"info": {
"version": "v1",
"title": "MyTestService"
},
"paths": {
"/api/Values": {
"get": {
"tags": [ "Values" ],
"operationId": "Get",
"consumes": [],
"produces": [ "text/plain", "application/json", "text/json" ],
"parameters": [],
"responses": {
"200": {
"description": "Success",
"schema": { "type": "string" }
}
}
}
}
},
"definitions": {
"LoginModel": {
"type": "object",
"properties": {
"username": { "type": "string" },
"password": { "type": "string" }
}
}
},
"securityDefinitions": {
"bearerAuth": {
"name": "Authorization",
"in": "header",
"type": "apiKey",
"description": "JWT Authorization header"
}
},
"security": [ { "bearerAuth": [] } ]
}
Swagger JSON V2.0 spec – Operation Scope
Swagger JSON V2.0 spec example for Operation level scope can be found as below,
{
"swagger": "2.0",
"info": {
"version": "v1",
"title": "MyTestService"
},
"paths": {
"/api/Pay": {
"get": {
"tags": [ "Values" ],
"operationId": "Get",
"consumes": [],
"produces": [ "text/plain", "application/json", "text/json" ],
"parameters": [
{
"name": "Authorization",
"in": "header",
"description": "JWT access token",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "Success",
"schema": {
"uniqueItems": false,
"type": "array",
"items": { "type": "string" }
}
},
"401": { "description": "Unauthorized" },
"403": { "description": "Forbidden" }
},
"security": [ { "bearerAuth": [] } ]
}
}
},
"definitions": {
"LoginModel": {
"type": "object",
"properties": {
"username": { "type": "string" },
"password": { "type": "string" }
}
}
}
}
References:
Do you have any comments or ideas or any better suggestions to share?
Please sound off your comments below.
Happy Coding !!
Please bookmark this page and share it with your friends. Please Subscribe to the blog to receive notifications on freshly published(2024) best practices and guidelines for software design and development.