Swashbuckle for C# (.NET): Complete Guide with Examples

What is Swashbuckle and why is it needed?

\n\n

Swashbuckle is a powerful library for the .NET platform that automatically generates interactive documentation for your Web APIs based on the OpenAPI standard (formerly known as Swagger). It integrates directly into ASP.NET Core applications and allows developers, testers, and API consumers to easily understand and interact with your endpoints.

\n\n

Why is it needed?

\n

\n
• Documentation automation: You don't need to manually write and maintain documentation. Swashbuckle analyzes your controllers, models, and attributes, creating up-to-date documentation on the fly.
\n
• Interactive interface (Swagger UI): The library provides a web interface where you can view all endpoints, their parameters, data models, and even execute test requests directly from the browser.
\n
• Standardization: OpenAPI is an industry standard. The generated documentation can be used to automatically generate client SDKs in different languages (JavaScript, Python, Java, etc.).
\n
• Simplified testing and debugging: Developers and QA engineers can quickly test APIs without using third-party tools like Postman (although Postman can also import OpenAPI specifications).
\n

\n\n

Swashbuckle consists of two main components: Swashbuckle.AspNetCore.Swagger (generation of OpenAPI JSON specification) and Swashbuckle.AspNetCore.SwaggerUI (display of the interactive interface).

\n\n

Installation

\n\n

Swashbuckle is installed via the NuGet package manager. You can use the Package Manager Console, .NET CLI, or the Visual Studio interface.

\n\n

Via .NET CLI (recommended)

\n

dotnet add package Swashbuckle.AspNetCore\n

\n\n

Via Package Manager Console in Visual Studio

\n

Install-Package Swashbuckle.AspNetCore\n

\n\n

This command will install the main package, which includes all necessary components: Swagger, SwaggerUI, and Swashbuckle.Core.

\n\n

Quick start with code example

\n\n

Let's look at the minimal setup of Swashbuckle for an ASP.NET Core Web API.

\n\n

1. Create a new Web API project

\n

dotnet new webapi -n MySwaggerApi\ncd MySwaggerApi\n

\n\n

2. Add Swashbuckle

\n

dotnet add package Swashbuckle.AspNetCore\n

\n\n

3. Configure Program.cs

\n

Open the Program.cs file and add the following lines:

\n\n

using Microsoft.OpenApi.Models;\n\nvar builder = WebApplication.CreateBuilder(args);\n\n// Add Swagger services\nbuilder.Services.AddEndpointsApiExplorer();\nbuilder.Services.AddSwaggerGen(c =>\n{\n    c.SwaggerDoc("v1", new OpenApiInfo\n    {\n        Title = "My Awesome API",\n        Version = "v1",\n        Description = "An example API to demonstrate Swashbuckle"\n    });\n});\n\nvar app = builder.Build();\n\n// Enable Swagger middleware\nif (app.Environment.IsDevelopment())\n{\n    app.UseSwagger();\n    app.UseSwaggerUI();\n}\n\napp.UseHttpsRedirection();\n\n// Example of a simple endpoint\nvar summaries = new[]\n{\n    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"\n};\n\napp.MapGet("/weatherforecast", () =>\n{\n    var forecast = Enumerable.Range(1, 5).Select(index =>\n        new WeatherForecast\n        (\n            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),\n            Random.Shared.Next(-20, 55),\n            summaries[Random.Shared.Next(summaries.Length)]\n        ))\n        .ToArray();\n    return forecast;\n})\n.WithName("GetWeatherForecast");\n\napp.Run();\n\nrecord WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)\n{\n    public int TemperatureF => 32 + (int)(TemperatureC / 0.55