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
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.
Andrew Halil is a blogger, author and software developer with expertise of many areas in the information technology industry including full-stack web and native cloud based development, test driven development and Devops.
