Implement Swagger In ASP.net Core 3.1 Web API

Hello Techies,

Today, this blog is going to be simple, we are just going to implement the Swagger UI for the Web API which works similar to the Postman. In simple words, we can say it is a tool which describes our API structure and functionality to call our API directly from the UI.

What is Swagger?

The Swagger is a set of rules which provides the users functionality to understand the structure of the REST API, and it can also be used to share documentation among product managers, testers, and developers, but can also be used by various tools to automate API related processes.

Implement Swagger

Let's just start with the empty project, so create a project ASP.Net Core Web API or MVC with .net core 3.1 (long-term access). Follow the following steps to start with the solution:

Step 1 - Open the Visual Studio (Currently I am using the Visual Studio 19) and Select the Project Type (I am using the Asp.net Core Web App MVC).

Step 2 - Add the title of the Project and then Click on the Next.

Step 3 - Now in this step Select your framework, I am using the framework (.net core 3.1) and Click on Create.

Now, we are going to add a package where you can use the NuGet Package Manager or Package Manage Console. I'll explain both:

  • For Package Manager, just go to Tools→ NuGet Package Manager → NuGet Package Manager 
    • in browse tab, search Swashbuckle. AspNetCore and install it.

Now, select the NuGet Package Swashbuckle. AspNetCore and then select your project then click on install (if you want to change the version then you can).

After clicking on the installation you will get the two pop-up dialogue, in this dialogue click on install and I Accept.

  • For Package Manager Console, go to Tools → NuGet Package Manager → Package Manager Console
    • in console, add the following command and execute it 
Install-Package Swashbuckle.AspNetCore 

Now, once the Installation is done, and we are going to implement it in our code for the UI Right? But, If you try to run the code and go to HTTP:localhost:[port number]/swagger/index.html then it will show you output similar to below:

So, what it means is we have installed the packages but not implemented till now.

So, go to the Startup.cs file.

Add the following code to the ConfigureServices Method.

services.AddSwaggerGen();
services.AddSwaggerGen(c =>
{
	c.SwaggerDoc("v1", new OpenApiInfo{
		Version = "v1",
		Title = "Implement Swagger UI",
		Description = "A simple example to Implement Swagger UI",
	});
});

Add the following code to the Configure Method of the Startup.cs file.

app.UseSwagger();
app.UseSwaggerUI(c =>{
	c.SwaggerEndpoint("/swagger/v1/swagger.json", "Showing API V1");
});

Now if you can check you will get an output like the following image, but we will not get any controller or any Methods information or structure information below that we will get just the Swagger Project Name and the Description as below : 

Now, in Swagger if we want to show some information of contact and license and some link then you can as below :

services.AddSwaggerGen();
services.AddSwaggerGen(c =>
{
	c.SwaggerDoc("v1", new OpenApiInfo{
		Version = "v1",
		Title = "Implement Swagger UI",
		Description = "A simple example to Implement Swagger UI",
		TermsOfService = new Uri("https://example.com/terms"),
		Contact = new OpenApiContact{
			Name = "Jay Pankhania",
			Email = "email@[domain].com",
			Url = new Uri("https://twitter.com/[twitterName]"),
		},
		License = new OpenApiLicense{
			Name = "License Information",
			Url = new Uri("https://example.com/license"),
		}
	});
});

In the output of the above code, you will get something like the following image.

Now, Sometimes we are getting the error like following : 

So, What this Error means is we have done something wrong or there is a missing method of the controller which could be an HTTP GET or HTTP POST, or we have added the Service or new controller, but we forget to add it to the startup. Let's regenerate one of these scenarios and resolve it.

Create new Controller function but forget to add the method.

(NOTE : I am talking about the functions which has given the Route but forget to give the Method Type)

Now, we are going to resolve this scenario what we are going to do is just provide it a method type, and it will resolve.

Now the output of the above code we will get the controller, and we can check it over the swagger UI. Similar to above method, we can make multiple methods and controllers as well.

I hope it will help you when you are going to create a new project or when you are getting any errors, you can ask any questions you have regarding the swagger that I can research and learn and improve and can answer your questions 


Next Recommended Reading Model Popup In ASP.NET Core 3.1