Swagger/OpenAPI for C# (.NET): Generation and API Documentation

Swagger/OpenAPI Generation for C# (.NET)

Swagger (now officially known as OpenAPI) is a powerful tool for designing, building, documenting, and using RESTful APIs. In the .NET ecosystem, generating OpenAPI specifications and interactive documentation has become an integral part of modern web service development. In this article, we will take a detailed look at how to configure automatic Swagger/OpenAPI generation in C# (.NET) applications using the Swashbuckle.AspNetCore library.

Swagger not only allows you to automatically create readable documentation but also provides an interactive interface (Swagger UI) for testing endpoints directly from the browser. This significantly speeds up development and integration between teams.

Installing and Configuring Swashbuckle in .NET

To get started, we need to install the Swashbuckle.AspNetCore package. This is the main package that includes the Swagger generator, Swagger UI, and integration with ASP.NET Core.

Installation via NuGet Package Manager Console:

Install-Package Swashbuckle.AspNetCore

Or via .NET CLI:

dotnet add package Swashbuckle.AspNetCore

After installing the package, you need to configure the services in the Program.cs file (or Startup.cs for older versions). Let's look at the minimal configuration for .NET 8 and above:

var builder = WebApplication.CreateBuilder(args);

// Add Swagger servicesbuilder.Services.AddSwaggerGen(c =>{    c.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo    {        Title = "My API",        Version = "v1",        Description = "Example API with Swagger documentation"    });});

builder.Services.AddControllers();

var app = builder.Build();

if (app.Environment.IsDevelopment()){    app.UseSwagger();    app.UseSwaggerUI(c =>    {        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");    });}

app.UseHttpsRedirection();app.MapControllers();

app.Run();

Key Features of Swashbuckle

• Automatic OpenAPI specification generation — the library analyzes your controllers, data models, and attributes, creating a JSON/YAML specification file.
• Interactive Swagger UI — a web interface where you can view endpoints, send requests, and see responses.
• XML comments support — if you add XML documentation to your controllers and models, Swagger will display them in the interface.
• Version grouping — you can create multiple versions of documentation for different API versions.
• Customization — the ability to customize the appearance, add headers, authentication schemes (JWT, Basic Auth), and much more.

Adding XML Comments for Documentation

To make your documentation informative, use XML comments. First, enable XML file generation in the project. Open the .csproj file and add:

<PropertyGroup>    <GenerateDocumentationFile>true</GenerateDocumentationFile>    <NoWarn>$(NoWarn);1591</NoWarn></PropertyGroup>

Then specify the path to the XML file in AddSwaggerGen:

builder.Services.AddSwaggerGen(c =>{    c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });        // Specify the path to the XML documentation file    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);    c.IncludeXmlComments(xmlPath);});

Now comments from your code will be displayed in the Swagger UI. Example controller with comments:

/// <summary>