Swashbuckle C# (.NET): Methoden, Beispiele, Installation |…

Was ist Swashbuckle und warum wird es benötigt?

Swashbuckle ist eine leistungsstarke Bibliothek für die .NET-Plattform, die automatisch interaktive Dokumentation für Ihre Web-APIs auf Basis des OpenAPI-Standards (früher bekannt als Swagger) generiert. Sie lässt sich direkt in ASP.NET Core-Anwendungen integrieren und ermöglicht es Entwicklern, Testern und API-Konsumenten, Ihre Endpunkte leicht zu verstehen und zu nutzen.

Warum ist das wichtig?

Automatisierte Dokumentation: Sie müssen keine Dokumentation manuell schreiben oder pflegen. Swashbuckle analysiert Ihre Controller, Modelle und Attribute und erstellt automatisch eine aktuelle Dokumentation.
Interaktive Oberfläche (Swagger UI): Die Bibliothek bietet eine Weboberfläche, in der Sie alle Endpunkte, deren Parameter, Datenmodelle anzeigen und sogar Testanfragen direkt aus dem Browser ausführen können.
Standardisierung: OpenAPI ist ein Industriestandard. Die generierte Dokumentation kann verwendet werden, um automatisch Client-SDKs in verschiedenen Sprachen (JavaScript, Python, Java usw.) zu generieren.
Vereinfachtes Testen und Debuggen: Entwickler und QA-Ingenieure können APIs schnell testen, ohne externe Tools wie Postman zu benötigen (obwohl Postman ebenfalls OpenAPI-Spezifikationen importieren kann).

Swashbuckle besteht aus zwei Hauptkomponenten: Swashbuckle.AspNetCore.Swagger (Generierung der OpenAPI-JSON-Spezifikation) und Swashbuckle.AspNetCore.SwaggerUI (Darstellung der interaktiven Oberfläche).

Installation

Swashbuckle wird über den NuGet-Paketmanager installiert. Sie können die Paketmanager-Konsole, die .NET CLI oder die Visual Studio-Oberfläche verwenden.

Über die .NET CLI (empfohlen)

dotnet add package Swashbuckle.AspNetCore

Über die Paketmanager-Konsole in Visual Studio

Install-Package Swashbuckle.AspNetCore

Dieser Befehl installiert das Hauptpaket, das alle erforderlichen Komponenten enthält: Swagger, SwaggerUI und Swashbuckle.Core.

Schnellstart mit Codebeispiel

Betrachten wir die minimale Konfiguration von Swashbuckle für eine ASP.NET Core Web API.

1. Erstellen Sie ein neues Web-API-Projekt

dotnet new webapi -n MySwaggerApi
cd MySwaggerApi

2. Fügen Sie Swashbuckle hinzu

dotnet add package Swashbuckle.AspNetCore

3. Konfigurieren Sie Program.cs

Öffnen Sie die Datei Program.cs und fügen Sie die folgenden Zeilen hinzu:

using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder(args);

// Swagger-Dienste hinzufügen
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo
    {
        Title = "My Awesome API",
        Version = "v1",
        Description = "Eine Beispiel-API zur Demonstration von Swashbuckle"
    });
});

var app = builder.Build();

// Middleware für Swagger aktivieren
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

// Beispiel für einen einfachen Endpunkt
var summaries = new[]
{
    "Eiskalt", "Kühl", "Frisch", "Mild", "Angenehm", "Warm", "Heiß", "Glühend heiß", "Schwül", "Sengend"
};

app.MapGet("/weatherforecast", () =>
{
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
})
.WithName("GetWeatherForecast");

app.Run();

record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}