Swagger (Swashbuckle)

What is Swagger

Swagger is an opensource tool that help you list, test and display your API features following the OpenAPI Specification

You can browse the website at Swagger.io to know everything about the product. The most useful part for us will be the SwaggerUI that will display a webpage which list our API capabilities directly from the code and not through an already obsolete static documentation. From that webpage, you will also be able to input your own parameter and test in live your endpoints.

Swashbuckle or NSwag

Here we will see how to use the Swashbuckle implementation. If you want to the difference between Swashbuckle and NSwag, here is the NSwag description from the Microsoft's doc (see "Useful links" for the full article):

The main reason to use NSwag is the ability to not only introduce the Swagger UI and Swagger generator, but to make use of the flexible code generation capabilities. You don't need an existing API—you can use third-party APIs that incorporate Swagger and let NSwag generate a client implementation. Either way, the development cycle is expedited and you can more easily adapt to API changes.

Adding Swagger to your project

Install Swashbuckle package

Swagger is available through a NuGet package named Swashbuckle.AspNetCore.

From the command line

1. Go to the Package Manager Console window
2. Execute Install-Package Swashbuckle.AspNetCore

From the NuGet Packages Manager

1. Right-click the project in Solution Explorer > Manage NuGet Packages
2. Set the Package source to "nuget.org"
3. Enter "Swashbuckle.AspNetCore" in the search box
4. Select the "Swashbuckle.AspNetCore" package from the Browse tab and click Install

Open Swagger page on run

When you run your API in debug mode from Visual Studio, you'll want to directly launch a browser and open swagger's homepage. A simple config will do this for your automatically.

From within Visual Studio 2017

Visual Studio will help you make this change easily through the solution properties.

From the code

You can do this change directly from the code with this simple change (see commit https://github.com/ylerjen/ExampleApi/commit/93b7d2fe73ac771ff4e1797ddcc25b978a08a714).

1. Access your <your-solution-folder>/Properties/launchSettings.json file (or create it if you don't have it yet).
2. Add this json properties "profiles": { "IIS Express": { "commandName": "IISExpress", "launchBrowser": true, "launchUrl": "swagger" } => launchUrl contains swagger as it's the default location for the SwaggerUI, but you'll have to change this value according your configuration if you customized the default location.

Customize Swagger page with examples

Swagger UI can also be completed with some examples like a Mock payload that can be directly used to test the endpoint. This can be done with the help of a NuGet package and here is how.

Install swashbuckle NuGet attributes

First install the swashbuckle.aspnetcore.examples NuGet package to your api project.

Create a swagger request example

In this previously installed package, you'll find some attribute like SwaggerRequestExampleAttribute. You can use it on your controller's method to describe a Mock payload.

First, add the attribute on your Controller's method. E.g : SwaggerRequestExample(typeof(MyDto), typeof(MyPayloadExampleProvider). The first param is just the Dto you use as the entry object. The second is your implementation of IExamplesProvider where you override GetExamples() to return your custom payload object.

Then add the OperationFilter instruction in your api's startup.cs file like :

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new Info { Title = "Example API", Version = "v1" });
    c.OperationFilter<ExamplesOperationFilter>();
});

See this commit for the whole implementation example

Useful links

https://docs.microsoft.com/en-us/aspnet/core/tutorials/web-api-help-pages-using-swagger?view=aspnetcore-2.1