NSwag Swagger API documentation in ASP.NET Core

Swagger or OpenAPI describes 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 use NSwag Swagger API documentation 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 Swagger API documentation using Swashbuckle in .NET Core, we learned about adding Swagger documentation in .NET Core API using Swashbuckle tooling.

In this post, we will see how to Swagger/OpenAPI documentation in .NET Core API using NSwag tooling.

Today in this article, we will cover below aspects,

Getting started

Create ASP.NET Core 3.1 or .NET 5 API

Add the NSwag Nuget package

PM> Install-Package NSwag.AspNetCore -Version 13.4.2

OR

Install it through Nuget Package Manager,

Update ConfigureServices() method

Add below line to ConfigureServices() method as shown below,

Below Swagger, middleware API works fine for ASP.NET Core 2.2 or above 3.0 version.

 public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllers();

      //OR for ASP>NET Core 2.2 
  //services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2

            services.AddSwaggerDocument(config =>
            {
                config.PostProcess = document =>
                {
                    document.Info.Version = "v1";
                    document.Info.Title = "MyTestService";
                    document.Info.Description = "My First Service";
                    document.Info.TermsOfService = "None";
                    document.Info.Contact = new NSwag.OpenApiContact
                    {
                        Name = "TheCodeBuzz",
                        Email = "[email protected]",
                        Url = "thecodebuzz.com"
                    };
                    document.Info.License = new NSwag.OpenApiLicense
                    {
                        Name = "Trademak ",
                        Url = "https://www.thecodebuzz.com"
                    };
                };
            });
        }

Update Configure() method

Please add below add the Swagger UI interface in the API pipeline.

            app.UseOpenApi();

            app.UseSwaggerUi3();

If using OpenAPI v3.0

If you are using OpenAPI v3.0 + for API documentation then please register document level metadata by registers an OpenAPI v3.0 as below,

Let’s see the swagger definition generated,

Enabling XML documentation for API

To create Swagger API level documentation please update the below settings in the project file. The XML file gets created in the output folder itself.

Please make sure to update the GenerateDocumentationFile property to ‘true‘ in csproj.

The above setting will generate documentation at each method level as below,

The swagger JSON file can be accessed via the below route locally.(Port number may vary for you).

 https://localhost:44367/swagger/v1/swagger.json 

NSwag also lets you define multiple Authentication schemes like JWT or OAuth2 etc.

Summary

In this post, we learned how to add swagger documentation using NSwag. Swagger or OpenAPI describes the standards and specifications for RESTFul API descriptions. In ASP.NET Core, it is simple to enable OpenAPI documentation using the Nswag Nuget package and tooling.

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.