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 security attribute 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 security attribute keyword to apply this scheme to the desired operation i.e at operation level.

References:

• JWT Authorization in Swagger OpenAPI with examples

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.