Testing of Web APIs is always a challenge because it exposes the end-point rather than the UI. Testing such things may have a dependency on third-party tools, such as fiddler and Post-Man, to Web API endpoints. Swagger can resolve this issue.

Introduction

 Testing of Web APIs is always a challenge because it exposes the end-point rather than the UI. Testing such things may have a dependency on third-party tools, such as fiddler and Post-Man, to Web API endpoints. Swagger can resolve this issue. It provides the UI representation of the RESTful APIs without any implementation logic. It allows the users to understand the capabilities of a service without any code access and it also reduces the amount of time to create a service document. Swagger generates the UI using the Swagger specification file (swagger.json) that is generated by Swagger tool based on service code. This file describes the capabilities of service; i.e., how many methods are supported by the service and provides information about method parameters. Using this file, Swagger UI generates client code. Following is an example of a swagger.json file. 

  Swagger can be implemented in ASP.net core web API using Swashbuckle.AspNetCore and NSwag package. Both are open source projects to generate Swagger documents for ASP.NET Core Web API. Additionally NSwag also provides the approaches to generate TypeScript client code as well as C# servercode for API. 

Configure Swagger in ASP.net Core Web API using Swashbuckle.AspNetCore

 Following are the step to configure Swagger in ASP.net Core Web API using Swashbuckle.AspNetCore. Step 1 – Install package Swashbuckle.AspNetCore Using the following command, we can install a Swashbuckle.AspNetCore package.

1. PM> Install-Package Swashbuckle.AspNetCore  

Step 2 – Configure Swagger middleware To add Swagger middle to the request pipeline, we need to AddSwaggerGen method in ConfigureService method of startup class. Here, we can define one or more Swagger documents. Startup.cs

1. public void ConfigureServices(IServiceCollection services)  
2. {  
3.     services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);  
4.     services.AddSwaggerGen(c =>  
5.     {  
6.         c.SwaggerDoc(“v1.0”, new Info { Title = “My Demo API”, Version = “1.0” });  
7.     });  
8. }  

If we want to enable this middleware, we need to call UseSwagger method in the configure method of startup class. Here also we need to configure SwaggerEndpoint to generate UI. The UseSwaggerUI is adding a static file middleware to load swagger.json file.

1. public void Configure(IApplicationBuilder app, IHostingEnvironment env)  
2. {  
3.     if (env.IsDevelopment())  
4.     {  
5.         app.UseDeveloperExceptionPage();  
6.     }  
7.     else  
8.     {  
9.         app.UseHsts();  
10.     }  
11.   
12.     app.UseHttpsRedirection();  
13.   
14.     app.UseSwagger();  
15.     app.UseSwaggerUI(c =>  
16.     {  
17.         c.SwaggerEndpoint(“/swagger/v1.0/swagger.json”, “My Demo API (V 1.0)”);  
18.     });  
19.     app.UseMvc();  
20. }  

The above steps are required to setup Swagger. If we want to launch Swagger in development environment using Visual Studio, one more change is required. To set Swagger UI, go to project property – debug tab and change Launch Browser value to “swagger”. 

 When we run the application, we can see following Swagger UI for ValuesContoller. 

 As we see here, it uses a different color code for each HTTP verb. When we click on any action method it will ask for parameter details and when we click on excecute button it will send a request to the web API. The Swagger requires minimum configuration to test our web API. It also shows XML comments when generating UI but that requires some configuration. The .net /.net core framework provides a way to write XML comment for the documentation. In .net core, we can enble XML comments by setup “XML documentation file” property under build tab of project property windows. 

 Swagger UI does not shows this documentation by default. We need to pass the path to IncludeXMLComments.

1. public void ConfigureServices(IServiceCollection services)  
2. {  
3.     services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);  
4.     services.AddSwaggerGen(c =>  
5.     {  
6.         c.SwaggerDoc(“v1.0”, new Info { Title = “My Demo API”, Version = “1.0” });  
7.         c.IncludeXmlComments(System.IO.Path.Combine(System.AppContext.BaseDirectory, “SwaggerDemo.xml”));  
8.     });  
9. }  

Configure Swagger in ASP.net Core Web API using NSwag

 Following are the step to configure Swagger in ASP.net Core Web API using NSwag.AspNetCore Step 1 – Install-Package NSwag.AspNetCore Using the following command, we can install package of NSwag.AspNetCore

1. PM> Install-Package NSwag.AspNetCore   

Step 2 – Configure Swagger middleware To add a Swagger middle to the request pipeline, we need to AddSwaggerDocument method in ConfigureService method of startup class. This method adds default document with name “V1”. If we want to add more than one document, call this method multiple times with a different document name. Startup.cs

1. public void ConfigureServices(IServiceCollection services)  
2. {  
3.     services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);  
4.     services.AddSwaggerDocument();  
5. }  

If want to enable this middleware, we need to call UseSwagger method in configure method of startup class. This method adds default route as “/swagger/{documentName}/swagger.json” Also we need to call UseSwaggerUi3 method to add the Swagger UI to request pipeline.

1. public void Configure(IApplicationBuilder app, IHostingEnvironment env)  
2. {  
3.     if (env.IsDevelopment())  
4.     {  
5.         app.UseDeveloperExceptionPage();  
6.     }  
7.     else  
8.     {  
9.         app.UseHsts();  
10.     }  
11.   
12.     app.UseHttpsRedirection();  
13.   
14.     app.UseSwagger();  
15.     app.UseSwaggerUi3();  
16.   
17.     app.UseMvc();  
18. }  

The above steps are required to set up Swagger. If we want to launch Swagger in development environment using Visual Studio, one more change is required. To set Swagger UI, go to project property – debug tab and change Launch Browser value to “swagger”. 

Summary

 Swagger helps us to test our web API without any third party tool and custom code. In this article I have explained how to configure Swagger using Swashbuckle and NSwag. You can view or download the source code from the GitHub link here.