Swagger OpenApi 3.0 JSON spec for Authorization Bearer
Today in this article, we shall see an example of Swagger OpenApi 3.0 JSON spec for Authorization Bearer within OpenAPI( Swagger V3.0) specification.
Today in this article, we will cover below aspects,
If you need to verify Swagger v2.0 then we will also see corresponding JSON files.
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 OpenApi 3.0 spec – Global security scheme
Below is a sample example for OpenAPI 3.0 swagger spec, which details how to represents the details for global level security scheme,
In OpenAPI 3.0 above specification is explained as below,
- Define the security scheme under
components/securitySchemes - Define type as “http” and schema as “bearer“
- Define the
securityattribute keyword to apply this scheme to the desired scope – global level
Swagger JSON OpenApi 3.0 spec – Operation security scheme
Below is a sample example for OpenAPI 3.0 swagger spec, which details how to represents the JSON for operation level security scheme,
Sample example,
{
"openapi": "3.0.1",
"info": {
"title": "TheCodeBuzz-Service",
"version": "v1"
},
"paths": {
"/api/Pay": {
"get": {
"tags": [
"Pay"
],
"responses": {
"200": {
"description": "Success",
"content": {
"text/plain": {
"schema": {
"$ref": "#/components/schemas/Employee"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/Employee"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/Employee"
}
}
}
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
}
},
"security": [
{
"bearerAuth": []
}
]
}
}
},
"components": {
"schemas": {
"Employee": {
"type": "object",
"properties": {
"id": {
"type": "string",
"nullable": true,
"readOnly": true
},
"name": {
"type": "string",
"nullable": true,
"readOnly": true
}
},
"additionalProperties": false
}
},
"securitySchemes": {
"bearerAuth": {
"type": "http",
"description": "JWT Authorization header using the Bearer scheme.",
"scheme": "bearer",
"bearerFormat": "JWT"
}
}
}
}
In OpenAPI 3.0 above specification is explained as below,
- Security scheme is defined under
components/securitySchemes - Define type as “http” and schema as “bearer“
- Define the
securityattribute keyword to apply this scheme to the desired operation i.e at operation level.
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.
