ASP.net core web api documentation with swagger/openApi

In the world of web api and microservices, understanding web api's methods and endpoints is quite challenging. Traditional way to create documentation as file with word or PDF. But it is very difficult to maintained and keeping documentation updated as per changes. Now swagger which also known as openAPI solves the problem of web api documentation and testing.

What is Swagger/OpenAPI?

Swagger is a language-agnostic specification for describing REST APIs. Swagger project was donated to OpenAPI Initiative where it is called as openAPI. So both these names are used interchangeably. Swagger/OpenAPI allows both human and computers to understand capabilities of web api without interacting its implementation (code, deployments etc). There are two main goals are

1. Minimize the time and effort to connect two disconnected services.
2. Minimize time and effort for web api documentation

In this document we will went through Swashbuckle.Aspnetcore and NSwag.net

Swashbuckle.Aspnetcore - Swashbuckle.aspnetcore is an open source project for .net core documentation.

NSwag.net - NSwag.net is another open source project for .net core web api documentation, additionally provide capabilities of creating C# and TypeScript clients for web api.

Starting with swashbuckle and aspnet core

Swashbuckle.AspNetCore mainly consists of three components

Swashbuckle.AspNetCore.Swagger - Swagger object and middleware to expose SwaggerDocument object as JSON.

Swashbuckle.AspNetCore.SwaggerGen - Swagger generator which builds SwaggerDocument directly from web api controllers and models. It typically combines swagger endpoint middleware to automatically expose swagger JSON.

Swashbuckle.AspNetCore.SwaggerUI - It interpret swagger json and create UI for web api.

For implementation, i am using visual studio 2019 with .Net core 3.1. Here are steps

1. Open visual studio 2019 and create a new project with template ASP.Net core web application and select web api type project
2. Install nuget pckage "Swashbuckle.AspNetCore" for now its pre-release so i am using version 5.0.0-rc5. Open Solution Explorer --> Right click to dependencies folder --> select manage nuget package option --> Search for Swashbuckle.AspNetCore --> Install
3. Next step is to modify our startup class to add swagger dependencies and middlewares

Import following namespace

using Microsoft.OpenApi.Models;

Add swagger generator to the services collection by adding below code to Startup.ConfigureServices method

services.AddSwaggerGen(conf =>
{
conf.SwaggerDoc("v1", new OpenApiInfo {
Title="Api documentation",
Version = "1.0.0"
});
});

Next enable middleware’s for serving generated swagger json and swagger ui by adding below code to startup.configure method

app.UseSwagger();

app.UseSwaggerUI(opt =>
{
opt.SwaggerEndpoint("/swagger/v1/swagger.json", "Web api documentation");

});

Now all should go as expected, run application with ctrl+F5 or F5 and hit URL baseurl/swagger (https://localhost:44313/swagger for my demo application).

In all above document it's minimum and siplest way to enable openAPI/swagger to web api. We can also extend this documentation to more information like api description, contact details and licence info etc. To extend we documentation we need provide all these details to services.AddSwaggerGen method under Startup.ConfigureServices as

services.AddSwaggerGen(conf =>
{ conf.SwaggerDoc("v1", new OpenApiInfo
{
Title = "Api documentation",
Version = "1.0.0",
Description = "Demo api for ducumentation",
License = new OpenApiLicense
{
Name = "Licence name",
Url = new Uri("https://licence_Terms_URL.com")
},
Contact = new OpenApiContact
{
Name = "Surender Tanwar",
Email = "tanwar.mydream3010@gmail.com",
Url = new Uri("https://github.com/Surender1987")
}
});
});

Addition to above we can also use XML comments for dumenation through swagger. It will automativally produce document from XML comment. To include xml comments for documentation we have to enable xml documentation file in project

Right click to solution ---> Properties ---> Select buld tab in left ---> Under output section select checkbox forr xml documentation file ---> Save with ctrl + s

Next, add following code to services.AddSwaggerGen under startup.configureservices method

// Set the comments path for the Swagger JSON and UI.
var xmlFile = $"{Assembly.GetEntryAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
conf.IncludeXmlComments(xmlPath);

Add xml comments to controller actions as example given below

///

/// Creates a TodoItem.
///

///
/// Sample request:
///
/// POST /Todo
/// {
/// "id": 1,
/// "name": "Item1",
/// "isComplete": true
/// }
///
///
///
/// A newly created TodoItem
/// Returns the newly created item
/// If the item is null

These all comments will be added to swagger UI