Swagger API documentation in .NET Core 2.2

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 will cover below aspects,

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.
• Good API documentation helps reducing dependencies between different teams working on API.
• It provides details of the capabilities the service owns.
• Serve the Swagger UI with the capability to Test the Web API.
• Client-side SDK generation
• Helps in API discovery.

In our last article, we will learn about adding Swagger documentation in .NET Core API using Swashbuckle. Other tools like NSwag can also be used for the same.

If you looking for adding swagger to ASP.NET Core 3.1 and above version then please visit the below article,

• Add Swagger API Documentation in ASP.NET Core 3.1

The above article will articulate a few breaking changes compare to ASP.NET Core 2.2 version.

If you are looking for some advance details like Swagger documentation customization or using JWT authorization please see below post,

• Use JWT Authorization token in swagger .NET Core WebAPI
• Customizing swagger API documentation in .NET core

Let’s add swagger to simple WebAPI sample as below,

Adding swagger definition in .NET Core (2.0 and above) is simply a 2-3 steps process.

1. Create a WebAPI sample service and Swashbuckle nuget package

One can use any version of .NET Core like 2.2 or 3.0 etc.

Please add below Swashbuckle NuGet package to your WebAPI using Command prompt or package manager console

       Command:          Install-Package Swashbuckle.AspNetCore

OR

This single NuGet package shall add all other required components as shown below and you need not have to add them explicitly,

• Swagger
• SwaggerUI
• SwaggerGen

2. Update ConfigureServices() method

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

 ///

public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
            services.AddSwaggerGen(
            {
                c.SwaggerDoc("v1", new Info { Title = "MyTestService", Version = "v1" });
            });
        }

3. Update Configure() method

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

  ///
            app.UseSwagger();
            app.UseSwaggerUI(
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "TestService");
            });

Let’s see swagger definition generated,

Let me reiterate again, If you are looking for some advance details like Swagger documentation customization or using JWT authorization please see below post,

• Use JWT Authorization token in swagger .Net Core 2.2 WebAPI
• Customizing swagger API documentation in .NET Core

Enabling XML documentation for API

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

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

The above setting will generate the required method-level documentation in the form of XML file in the project root directory. Please update the Configure method as below to read this XML file.

Update to Configure method for XML

public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Info { Title = "MyTestService", Version = "v1" });
                var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
                var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
                c.IncludeXmlComments(xmlPath);

            });
        }

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:44354/swagger/v1/swagger.json 

Please note that in .NET Core 2.2 default swagger route used will be “/swagger/{documentName}/swagger.json” . The swagger definition would give you an error like Failed to load API definition in Swagger for configuring the same if hosting in IIS or other cloud environments like Azure etc.

Please visit the below article to properly define Swagger route,

• Swagger error route fixing using {documentName} in .NET Core

Summary:

Its simple to enable Swagger API documentation within the .NET Core API using the Swashbuckle Nuget package. Once enabled swagger provides the advantage of understanding the REST API (for developers ) consuming Web API. It provides easy ready API documentation and providing details of the capabilities an organization owns. Good API documentation helps reducing dependencies between different teams working on API.

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.