NSwag JWT Token Authorization OpenAPI Documentation in ASP.NET Core

OpenAPI describes the standards and specifications for the RESTFul API description. These specifications are an attempt to create a universal and language agnostic description for describing the REST API. Today in this article, we shall see how to enable NSwag JWT Token Authorization in ASP.NET Core.

Benefits of Open API specification :

• The open specification provides the advantage of understanding the RESTFul services easily (especially if developers are consuming any new Web API ) plus
• Helps provide easy ready documentation saving time
• It provides details of the capabilities the service owns.
• Serve the Swagger UI to browse and test the web API.
• Client-side SDK generation
• Helps in API discovery.

In our last article on NSwag Swagger API documentation in ASP.NET Core we learned about the basics of adding Documentation in ASP.NET Core API using NSwag.

Today in this article, we will cover below aspects,

In this post, we will see how to enable JWT (JSON web token) authentication in Swagger/OpenAPI documentation in ASP.NET Core API using NSwag tooling.

Let’s continue from our previous article and extend it to JWT authentication.

We already had added below Nuget packages to the project,

Add NSwag Nuget package

PM> Install-Package NSwag.AspNetCore -Version 13.4.2

OR

Install it through Nuget Package Manager,

The above updated NuGet package adds services required for OpenAPI 3.0 generation and exposes various extension methods like,

• AddOpenApiDocument
• AddSwagger
• AddSwaggerDocument

Update ConfigureServices() method

Here below please define the API ApiSecuritySchemeTyp as ApiKey with JWT key location in the header.

 services.AddOpenApiDocument(document =>
            {
                document.AddSecurity("JWT", Enumerable.Empty<string>(), new OpenApiSecurityScheme
                {
                    Type = OpenApiSecuritySchemeType.ApiKey,
                    Name = "Authorization",
                    In = OpenApiSecurityApiKeyLocation.Header,
                    Description = "Type into the textbox: Bearer {your JWT token}."
                });

                document.OperationProcessors.Add(
                    new AspNetCoreOperationSecurityScopeProcessor("JWT"));
            });

Add Swagger UI in API pipeline

Please add below the Application builder extension to add the Swagger UI interface in the API pipeline.

Please update the Configure() method for the below,

            app.UseOpenApi();

            app.UseSwaggerUi3();

NSwag JWT Authorize button on Swagger UI

Once you run API, Authorize button will be visible in swagger UI.

Please provide username and password value and click on Authorize.

Sample JWT Token as below,

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
eyJleHAiOjE1ODcyNTk2NzQsImlzcyI6Imh0dHBzOi8vbG9jYWxob3N0OjQ0MzQxIiwiYXVkIjoiaHR0cHM6Ly9sb2NhbGhvc3Q6NDQzNDEifQ.
q5E0b5TZNP1SLUcRtImV4Sju-xIqzUkSReL67NmGX6k

That’s all, you are all set to use NSwag with a JWT authentication enabled.

This authentication will be used for all API in the service as it’s global in nature.

NSwag JWT -Success(200) response

For a valid JWT token, you shall receive 200 HttpResponse

UnAuthorized(401) reponse

For invalid JWT token, you shall receive 401 UnAuthorized responses,

Thats All !! Happy Coding!!

If interested in how to secure API using JWT Authentication in ASP.NET Core, please visit below article,

• JWT Authentication in ASP.NET Core ASP.NET Core

Summary

OpenAPI describes the standards and specifications for RESTFul API descriptions. In this post, we learned how to add Open API documentation using NSwag tooling with JWT token authorization.

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.