In this post, I am going to discuss what is Swagger and Swashbuckle, and how to generate Swagger UI with ASP.NET Core 2 Web API. You can download the source code of this tutorial here.

Swagger in a nutshell

Swagger is a Specification(set of rules) for documenting REST API. It also provides tooling to generate documentation from code. A detailed description can be found here

What is Swashbuckle

Swashbuckle is a .NET implementation of Swagger. You can generate Swagger documents and Swagger UI using Swashbuckle.

Adding and Configuring Swashbuckle

I am going to use an existing ASP.NET WEB-API for this demo, you can find the complete working sample on GitHub. You can create a new WEB-API project or u can try this on existing WEB-API.

Add NuGet package Swashbuckle.AspNetCore, using your favorite method of adding a NuGet package.

Open Startup.cs, in ConfigureServices method, add swagger to services collection:

services.AddSwaggerGen(config =>
{
    config.SwaggerDoc("v1", new Info { Title = "My Api", Version = "V1" });
});

 In Configure method of Startup.cs file, add Swagger middleware:

app.UseSwagger();

After you have added Swagger middleware to the request pipeline, you should start getting Swagger generated JSON at the URL {baseUrl}/swagger/v1/swagger.json, here is how it looks in the sample project:

 

Now its time to add Swagger UI, in Configure method of Startup.cs file, add following line of code after app.UseSwagger(); :

app.UseSwaggerUI(config => { config.SwaggerEndpoint("v1/swagger.json", "My API V1"); });

Now, Swagger UI is available at {baseUrl}/swagger :

 

If you compare Swagger UI and ProductsController side by side, you can map Controller and Actions:

Moreover, you can call the APIs from this UI, just click on GET and then click the button "Try it out!" it will call the API and display the response:

 

So, how Swashbuckle generates documentation and UI for your WEB-API? It goes through all your Controllers and Actions, and reads the routes and other attributes and generates the documentation. So, you need to have attribute based routes for Swashbuckle to generate documentation and UI.

 

How to Improve the Documentation?

Just adding Swashbuckle and generating documentation and UI was a great start, but how do you improve the documentation? 

 

To generate the XML documentation file, In Visual Studio, right-click the project and go to properties, in Build tab, check the XML documentation option:

Now, every time you build the project, it will generate the XML documentation file at the output location.

Now let's add XML comments to the Action methods, for example:

/// <summary>
/// Gets the Product by Product ID.
/// </summary>
/// <param name="id">Product ID.</param>
/// <returns>Product</returns>
[HttpGet("{id}")]
public IActionResult Get(int id)
{
    if (!_products.Any(p => p.ProductId == id))
    {
        return NotFound();
    }
    return Ok(_products.Where(p => p.ProductId == id).First());
}

Run the application and navigate to Swagger UI at {baseUrl}/swagger and you can see the XML documentation included in the Swagger UI:

 

With just a couple of lines of code, we were able to add Swagger documentation and UI to our WEB-API project.

You can find the code for this post here.

Have any questions or suggestions? Please drop a comment in the section below.