ASP.NET Core-WebApi with Swagger

2 minute read

OpenAPI Specification (formerly Swagger Specification) is an API description format for REST APIs. An OpenAPI file allows you to describe your entire API. API specifications can be written in YAML or JSON. The format is easy to learn and readable to both humans and machines.

Swagger is a set of open-source tools built around the OpenAPI Specification that can help you design, build, document and consume REST APIs.

Swagger Document is defined with proper Title and Version details. “/swagger/{documentName}/swagger.json”.

Swashbuckle

Swashbuckle provides auto generation of Swagger 2.0 and related UI.

  • Add package Swashbuckle.AspNetCore

  • Register service:

services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "API", Version = "v1"});
});

  • Add service to pipeline:

{yourBaseUrl}/swagger/v1/swagger.json

app.UseSwagger();

{yourBaseUrl}/swagger

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

Edit csproj to generate document:

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

When returning IActionResult, you should attribute your action with all the ProducesResponseType you need to cover the results of your action:

[HttpPost]
[ProducesResponseType(typeof(MyRequest), 200)]
[ProducesResponseType(typeof(IDictionary<string, string>), 400)]
[ProducesResponseType(typeof(void), 400)]
[ProducesResponseType(typeof(void), 404)]
[ProducesResponseType(typeof(void), 409)]
public async Task<IActionResult> Post([FromBody] MyRequest request)

NSwag

NSwag is a Swagger/OpenAPI 2.0 and 3.0 NSwag combines the functionality of Swashbuckle (OpenAPI/Swagger generation) and AutoRest (client generation) in one toolchain.

  • Register service:
services.AddOpenApiDocument();
  • Add service to pipeline: {yourBaseUrl}/swagger
app.UseOpenApi();
app.UseSwaggerUi3();

Ways to use the toolchain:

  • NSwag.MSBuild

Install nuget package: NSwag.MSBuild

Download a sample config: https://github.com/RicoSuter/NSwag/blob/master/src/NSwag.Sample.NET50/nswag.json

Update config:

{
  "runtime": "Net50",

  "documentGenerator": {
    "aspNetCoreToOpenApi": {
      "project": "Api.csproj", // your project

      "noBuild": true,
      "defaultPropertyNameHandling": "CamelCase",
      "documentName": "v3",
      "output": "wwwroot/api/openapi.json",  // pth to specification
      "outputType": "OpenApi3",  // OpenApi3 OR Swagger2
    }
  },
  "codeGenerators": {}
}

Add target to csproj:

<Target Name="NSwag" AfterTargets="PostBuildEvent" Condition=" '$(Configuration)' == 'Debug' ">
    <Message Importance="High" Text="$(NSwagExe_Net50) run nswag.json /variables:Configuration=$(Configuration)" />

    <Exec WorkingDirectory="$(ProjectDir)" EnvironmentVariables="ASPNETCORE_ENVIRONMENT=Development" Command="$(NSwagExe_Net50) run nswag.json /variables:Configuration=$(Configuration)" />

    <Delete Files="$(ProjectDir)\obj\$(MSBuildProjectFile).NSwag.targets" />

  </Target>
  • Nswag npm

Install npm package: npm install nswag -g nswag help nswag version /runtime:Net50

nswag aspnetcore2openapi /file:pathto/nswag.json /assembly:pathto/api.dll" /runtime:Net50 /output:pathto/openapi.json
  • NSwagStudio

Download the MSI : NSwagStudio Then generate the specification.

  • In your C# code (Not recommanded)
services.AddOpenApiDocument(document => document.DocumentName = "v1");
services.AddSwaggerDocument(document => document.DocumentName = "v2");

app.UseOpenApi(); // serve documents (same as app.UseSwagger())
app.UseSwaggerUi3(); // serve Swagger UI
app.UseReDoc(); // serve ReDoc UI

Serve multiple documents (chain):

app.UseOpenApi(options =>
            {
                options.DocumentName = "openapiv3";
                options.Path = "/api/openapi.json";

            }
                );// serve OpenAPI/Swagger documents

app.UseSwaggerUi3(settings =>
{
    settings.Path = "/api";
    settings.DocumentPath = "/api/openapi.json";
});  // serve Swagger UI

app.UseOpenApi(p => p.Path = "/swagger/{documentName}/swagger.json");
app.UseSwaggerUi3(p => p.DocumentPath = "/swagger/{documentName}/swagger.json");

Use multiple routes:

app.UseSwaggerUi3(options =>
{
  // Add multiple OpenAPI/Swagger documents to the Swagger UI 3 web frontend
  options.SwaggerRoutes.Add(new SwaggerUi3Route("Swagger", "/swagger/v1/swagger.json"));
  options.SwaggerRoutes.Add(new SwaggerUi3Route("Openapi", "/openapi/v1/openapi.json"));

  // Define web UI route
  options.Path = "/swagger_all";
});

Generate specification from WebApi controller

Install nuget:

NSwag.Generation.WebApi

var settings = new WebApiOpenApiDocumentGeneratorSettings
{
    DefaultUrlTemplate = "api/{controller}/{action}/{id}"
};
var generator = new WebApiOpenApiDocumentGenerator(settings);
var document = await generator.GenerateForControllerAsync<PersonsController>();
var swaggerSpecification = document.ToJson();