Common features in ASP.NET Core 2.1 WebApi: Documenting



Provide a list of the services that are offered, for each one, how to call them and the structure of the response that is returned is also an essential feature for a Web API.

In this article, we will talk about Swagger.

Swagger tools takes the hard work out of generating and maintaining your API docs, ensuring your documentation stays up-to-date as your API evolves.

The Swagger framework for ASP.NET Core is an open source implementation based on the OpenAPI specification born in 2010.


Download this package:

PM> Install-Package Swashbuckle.AspNetCore -Version 4.0.1

Configuring Startup.cs 

It’s pretty simple to configure and activate Swagger.

First let’s add Swagger in ConfigureServices method:

public void ConfigureServices(IServiceCollection services)
   services.AddSwaggerGen(c =>
      c.SwaggerDoc("v1", new Info { Title = "My API + profiler integrated on top left page", Version = "v1" });
      c.AddSecurityDefinition("Bearer", new ApiKeyScheme
         Description = "JWT Authorization header using the Bearer scheme. Example: \"Authorization: Bearer {token}\"",
         Name = "Authorization",
         In = "header",
         Type = "apiKey"
      c.AddSecurityRequirement(new Dictionary<string, IEnumerable<string>>
         { "Bearer", new string[] { } }

Adding the document needs only one line:

c.SwaggerDoc(“v1”, new Info { Title = “My API + profiler integrated on top left page”, Version = “v1” });

It defines only the version, and the title of the documentation.

The rest below is there only for enable Authorization with a bearer token. In this serie of article I’m using bearer token, so you can replicate everything I do in this serie if you follow the serie since the first article.

Now let’s activate the middleware that serves Swagger and the middleware that serves the Swagger UI:

// Enable middleware to serve generated Swagger as a JSON endpoint.

// Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.), 
app.UseSwaggerUI(c =>
   c.RoutePrefix = "api-doc";
   c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");

I added here  a RoutePrefix named “api-doc” in order to build a friendly Url when you want to display the Swagger UI.


Now if we run the WebApi Swagger UI page, it should look like this:

We have the title as we typed it ine the Startup configurations, our routes as documentation and the Authorize button.

Let’s try now to test a route with the Authorization, because our routes are protected with a Bearer Token.

Set up the token value

Open the popup after clicking on the Authorize button and set up the value like this: bearer “Your token”:

Then press Authorize button again in the popup:

Calling the route

Like the picture below, the call should succeed:


You saw how to add easily documentation in your WebApi.

That’s a nice feature to have when you create a WebAPI.

I hope you will now have the reflex to add it to your WebApis 😉

Written by


Anthony is a specialist in Web technologies (14 years of experience), in particular Microsoft .NET and learns the Cloud Azure platform. He has received twice the Microsoft MVP award and he is also certified Microsoft MCSD and Azure Fundamentals.
%d bloggers like this: