Swagger/OpenAPI für C# (.NET): Generierung und Dokumentation von APIs

Swagger/OpenAPI Generierung für C# (.NET)

\n\n

Swagger (jetzt offiziell als OpenAPI bekannt) ist ein leistungsstarkes Werkzeug zum Entwerfen, Erstellen, Dokumentieren und Nutzen von RESTful APIs. Im .NET-Ökosystem ist die Generierung von OpenAPI-Spezifikationen und interaktiver Dokumentation zu einem wesentlichen Bestandteil der Entwicklung moderner Webdienste geworden. In diesem Artikel betrachten wir im Detail, wie Sie die automatische Generierung von Swagger/OpenAPI in C# (.NET)-Anwendungen mit der Bibliothek Swashbuckle.AspNetCore einrichten.

\n\n

Swagger ermöglicht nicht nur die automatische Erstellung lesbarer Dokumentation, sondern bietet auch eine interaktive Oberfläche (Swagger UI) zum Testen von Endpunkten direkt im Browser. Dies beschleunigt die Entwicklung und Integration zwischen Teams erheblich.

\n\n

Installation und Einrichtung von Swashbuckle in .NET

\n\n

Um zu beginnen, müssen wir das Paket Swashbuckle.AspNetCore installieren. Dies ist das Hauptpaket, das den Swagger-Generator, die Swagger-UI und die Integration mit ASP.NET Core enthält.

\n\n

Installation über die NuGet Package Manager Console:

\n

Install-Package Swashbuckle.AspNetCore

\n\n

Oder über die .NET CLI:

\n

dotnet add package Swashbuckle.AspNetCore

\n\n

Nach der Installation des Pakets müssen die Dienste in der Datei Program.cs (oder Startup.cs für ältere Versionen) konfiguriert werden. Betrachten wir eine minimale Konfiguration für .NET 8 und höher:

\n\n

var builder = WebApplication.CreateBuilder(args);\n\n// Swagger-Dienste hinzufügen\nbuilder.Services.AddSwaggerGen(c =>\n{\n    c.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo\n    {\n        Title = "My API",\n        Version = "v1",\n        Description = "Beispiel-API mit Swagger-Dokumentation"\n    });\n});\n\nbuilder.Services.AddControllers();\n\nvar app = builder.Build();\n\nif (app.Environment.IsDevelopment())\n{\n    app.UseSwagger();\n    app.UseSwaggerUI(c =>\n    {\n        c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");\n    });\n}\n\napp.UseHttpsRedirection();\napp.MapControllers();\n\napp.Run();

\n\n

Hauptfunktionen von Swashbuckle

\n\n

\n
• Automatische Generierung der OpenAPI-Spezifikation — Die Bibliothek analysiert Ihre Controller, Datenmodelle und Attribute und erstellt eine JSON/YAML-Spezifikationsdatei.
\n
• Interaktive Swagger-UI — Eine Weboberfläche, in der Sie Endpunkte anzeigen, Anfragen senden und Antworten sehen können.
\n
• Unterstützung für XML-Kommentare — Wenn Sie Ihren Controllern und Modellen XML-Dokumentation hinzufügen, zeigt Swagger diese in der Oberfläche an.
\n
• Versionierung — Sie können mehrere Versionen der Dokumentation für verschiedene API-Versionen erstellen.
\n
• Anpassung — Möglichkeit, das Erscheinungsbild anzupassen, Header, Authentifizierungsschemata (JWT, Basic Auth) und vieles mehr hinzuzufügen.
\n

\n\n

Hinzufügen von XML-Kommentaren für die Dokumentation

\n\n

Damit Ihre Dokumentation informativ ist, verwenden Sie XML-Kommentare. Aktivieren Sie zunächst die Generierung der XML-Datei im Projekt. Öffnen Sie die .csproj-Datei und fügen Sie hinzu:

\n\n

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

\n\n

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

\n\n

builder.Services.AddSwaggerGen(c =>\n{\n    c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });\n    \n    // Pfad zur XML-Dokumentationsdatei angeben\n    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";\n    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);\n    c.IncludeXmlComments(xmlPath);\n});

\n\n

Jetzt werden die Kommentare aus Ihrem Code in der Swagger-UI angezeigt. Beispiel eines Controllers mit Kommentaren:

\n\n

/// <summary>\n