Swagger For ASP.NET Core API 2.2

Introduction

 
Swagger is a framework which is used to document the Web APIs. In this article, we are going to see how to enable swagger for our Web API which is developed using ASP.NET Core 2.2.

Prerequisites
 
If you are new to ASP.NET Core API, please go through my previous article where I have explained how to get started with ASP.NET Core API projects.  

Tooling
 
Visual Studio 2017 and later
 

Swagger in ASP.NET Core API 2.2

 
I have created an ASP.NET Core 2.2 API application using Visual Studio 2019.
 
Model class, Employee.cs
  1. public class Employee  
  2.   {  
  3.       [Key]  
  4.       public int EmployeeID { getset; }  
  5.       public string Name { getset; }  
  6.   }  
Context class, EmployeeContext.cs
  1. public class EmployeeContext : DbContext  
  2.   {  
  3.       public EmployeeContext(DbContextOptions options) : base(options)  
  4.       {  
  5.       }  
  6.       public DbSet<Employee> Employees { getset; }     
  7.   
  8.   }  
We are connected with the back-end SQL database using Entity Framework Core code-first approach which I have explained in my previous article.
 

Scaffolding the controller


Right click the Controllers folder and go to Add-> Controller - > choose API controller with actions using Entity Framework.
 
Swagger For ASP.NET Core API 2.2 
 
Swagger For ASP.NET Core API 2.2
 
Once the scaffolding is done, you will get an API to perform a CRUD operation in the Employee entity.

Now, it’s time to prepare a document for an API using Swagger. 
 
Go to NuGet Package Manager from Tools -> NuGet Package Manager-> Manage NuGet packages for solution - > and search for swashbuckle for ASP.NET Core.
 
Swagger For ASP.NET Core API 2.2
 
Go to the startup.cs file and add the following code to the ConfigureService method.
  1. services.AddSwaggerGen(c=> { c.SwaggerDoc("v1"new Info { Title = "Employee API", Version = "V1" });  
  2.             });   
The above code is used to add the swagger document generation to the service.
 
Add the following code in the Configure method.
  1. app.UseSwagger();  
  2.             app.UseSwaggerUI(c=> {  
  3.                 c.SwaggerEndpoint("/swagger/v1/swagger.json""post API V1");  
  4.                 });  
The above code is used to define the end points for the Swagger UI
 
Let’s run the application.
 
Switch to the Swagger UI (localhost:44336/swagger/index.html) . You can find the documentation of all your APIs as shown in the following picture.
 
Swagger For ASP.NET Core API 2.2
 
Open the Employee POST API. You can find that the status code is 200 as shown in below figure but this is not a case all the time, because sometimes, we get a Bad request or some error might occur. Once the record is created, the status code should be 201 for the post request. Swashbuckle always statically analyzes the API. It needs more metadata to generate the detailed documents.
 
Swagger For ASP.NET Core API 2.2
 

ASP.NET Core Web API Analyzer


Web API Analyzer is used to add those metadata as an attribute to our Web API. Install Web API Analyzer for ASP.NET Core using NuGet Packager Manager.
 
Swagger For ASP.NET Core API 2.2
 
Once the package is installed, you can notice a warning in the method, as shown in the below figure.
 
Swagger For ASP.NET Core API 2.2
 
Do the changes based on the suggestion from Visual Studio.
 
Swagger For ASP.NET Core API 2.2
 
So, based on the return action, the attribute will be added which gives more metadata information for Swagger to generate a more detailed document.

Now, run the application and go to the Swagger UI.

Open the POST API.
 
Swagger For ASP.NET Core API 2.2
 
From the above image, you can notice that the status code of the post is now changed to 201 as expected. Apart from this change, we also get the documentation for the default code.
 

Conclusion


We have seen how Swagger helps us to document the Web API created using ASP.NET Core and we have also seen the benefits of using the Web API Analyzer for ASP.NET Core. I hope you have enjoyed this article. Your valuable feedback, questions, or comments about this article are always welcomed.