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

public class Employee
  {
      [Key]
      public int EmployeeID { get; set; }
      public string Name { get; set; }
  }

Context class, EmployeeContext.cs

public class EmployeeContext : DbContext
  {
      public EmployeeContext(DbContextOptions options) : base(options)
      {
      }
      public DbSet<Employee> Employees { get; set; }

  }

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.

 

 

 

 

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.

 

 

Go to the startup.cs file and add the following code to the ConfigureService method.

services.AddSwaggerGen(c=> { c.SwaggerDoc("v1", new Info { Title = "Employee API", Version = "V1" });
            });

The above code is used to add the swagger document generation to the service.

 

Add the following code in the Configure method.

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

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.

 

 
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.

 

 

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.

 

 

Once the package is installed, you can notice a warning in the method, as shown in the below figure.

 

 

Do the changes based on the suggestion from Visual Studio.

 

 

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.

 

 

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.