Swagger documentation
.NET Core ASP.NET Core C# OpenAPI Swagger Visual Studio Web API

How to Add Swagger UI to a Web API

Welcome to today’s post.

The Open API specification is an API description format for REST APIs which allows you to describe the API for your Web API service.

Swagger is a tool which is used to implement the Open API specification and is a useful package for improving the documentation of your Web API controllers in your web application or micro service.

I will show you how to install and configure the Swashbuckle NuGet packages that use the Swagger UI to document your Web APIs.

Step 1 – Installing Swagger UI

Open Package Manager.

Search for “Swashbuckle”

Select and add the following packages:

Swashbuckle.AspNetCore.Swagger

Swashbuckle.AspNetCore.SwaggerGen

Swashbuckle.AspNetCore.SwaggerUI

Accept each package installation.

After installation, you should see all three Swagger packages under the NuGet folder:

Step 2 – Configuring swagger

Next, configure your middleware as follows:

Open Startup.cs.

In ConfigureServices(), add the line that injects the SwaggerGen provider:

public void ConfigureServices(IServiceCollection services)
{
	...

      	// Inject ISwaggerProvider with defaulted settings
         services.AddSwaggerGen(c =>
         {
             c.SwaggerDoc("v1", new Swashbuckle.AspNetCore.Swagger.Info { Title = "BookLoan API", Version = "v1" });
         });
}

In Configure(), add the lines:

public void Configure(
	IApplicationBuilder app, 
	IHostingEnvironment env, 
	ILoggerFactory loggerFactory)
{
        . . .

      	app.UseSwagger();

      	app.UseSwaggerUi();
  }

Also don’t forget to include namespace Swashbuckle.AspNetCore.

Build and run the application.

Step 3 – Remediations

If you don’t see the swagger.json file generated then try the following:

Remove your controller class routing attributes.
[Route("api/[controller]")]
public class BookController : Controller

to

public class BookController : Controller
Replace your controller action class routing attributes with REST attributes (HTTPGET, HTTPPOST, HTTPPUT, HTTPDELETE)

Below is an example replacement with a HTTP GET REST attribute:

[Route("api/[controller]/Details/{id}")]
[Authorize(Policy = "BookReadAccess")]
public async Task<ActionResult> Details(int id)
{
	…
}

to

[HttpGet("api/[controller]/Details/{id}")]
[Authorize(Policy = "BookReadAccess")]
public async Task<ActionResult> Details(int id)
{
	…
}

Add the [NoAction] attribute to any public members in your controllers.

This is self-explanatory.

Step 4 – Testing the Swagger UI generation

Run the application.

Browse to

http://[server]/swagger

The site will redirect to

http://[server]/swagger/index.html

The page like the one below will show:

Drill into a GET and POST and check the input parameters and output documentation.

A typical HTTP GET method is shown:

A typical HTTP POST method is shown:

That’s all!

Hope you learned something useful and thanks for viewing this post.

Social media & sharing icons powered by UltimatelySocial