Swagger/OpenAPI-Generierung für C# (.NET): Swashbuckle und NSwag

Swagger/OpenAPI-Generierung für C# (.NET): Swashbuckle und NSwag

Die Dokumentation von REST-APIs ist ein wesentlicher Bestandteil der modernen Entwicklung mit C# (.NET). Die OpenAPI-Spezifikation (früher bekannt als Swagger) ermöglicht es, Endpunkte, Datenmodelle, Parameter und Antworten in einem einheitlichen, maschinenlesbaren Format (JSON/YAML) zu beschreiben. Im .NET Core / .NET 5+ Ökosystem gibt es zwei Hauptwerkzeuge zur automatischen Generierung von OpenAPI-Spezifikationen: Swashbuckle.AspNetCore und NSwag. Beide Werkzeuge integrieren sich in ASP.NET Core, analysieren Ihren Code und erstellen eine interaktive Dokumentation (Swagger UI).

Swashbuckle.AspNetCore: Die klassische Wahl

Swashbuckle ist das beliebteste Paket zur Generierung von Swagger/OpenAPI in .NET. Es erstellt automatisch eine Spezifikation basierend auf Controllern, Routing-Attributen und Modellannotationen. Es unterstützt OpenAPI 3.0 und Swagger 2.0.

Installation und Basiskonfiguration

dotnet add package Swashbuckle.AspNetCore

Fügen Sie in der Datei Program.cs (oder Startup.cs für ältere Versionen) Dienste und Middleware hinzu:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();builder.Services.AddEndpointsApiExplorer();builder.Services.AddSwaggerGen(c =>{    c.SwaggerDoc("v1", new OpenApiInfo    {        Title = "Meine API",        Version = "v1",        Description = "Beispiel-API für eine Bildungswebsite"    });});

var app = builder.Build();

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

app.MapControllers();app.Run();

Nach dem Start rufen Sie die Adresse /swagger auf – es öffnet sich eine interaktive Benutzeroberfläche, in der Sie Endpunkte direkt im Browser testen können.

Hinzufügen von XML-Kommentaren

Damit Beschreibungen aus XML-Kommentaren in die Dokumentation aufgenommen werden, aktivieren Sie die XML-Generierung in der .csproj-Datei:

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

Geben Sie dann den Pfad zur XML-Datei in AddSwaggerGen an:

builder.Services.AddSwaggerGen(c =>{    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);    c.IncludeXmlComments(xmlPath);});

Jetzt werden die Kommentare aus dem Code in der Swagger-Benutzeroberfläche angezeigt.

Beispiel-Controller mit Annotationen

[ApiController][Route("api/[controller]")]public class ProductsController : ControllerBase{    /// <summary>    /// Alle Produkte abrufen    /// </summary>    [HttpGet]    public ActionResult<IEnumerable<Product>> GetAll()    {        return Ok(new List<Product>());    }

    /// <summary>    /// Produkt nach ID abrufen    /// </summary>    /// <param name="id">Produkt-ID</param>    [HttpGet("{id}")]    public ActionResult<Product> GetById(int id)    {        return Ok(new Product { Id = id, Name = "Beispiel" });    }}

NSwag: Universelles Werkzeug mit Client-Generierung

NSwag ist eine leistungsfähigere Alternative. Neben der Dokumentationsgenerierung kann es C#-Clients für APIs, TypeScript-Clients erstellen und Code basierend auf externen OpenAPI-Spezifikationen generieren.

Installation und Konfiguration

dotnet add package NSwag.AspNetCore

Konfiguration in Program.cs:

builder.Services.AddOpenApiDocument(config =>{    config.Title = "Meine API (NSwag)";    config.Version = "v1";    config.Description = "API, generiert mit NSwag";});

// ...