Dokumentieren einer API mithilfe von Swashbuckle
Swashbuckle ist ein NuGet-Paket, das eine Möglichkeit bietet, die Swagger-Dokumentation für ASP.NET-Web-API Projekte automatisch zu generieren. Swagger hilft Entwickler*innen dabei, RESTful-APIs zu entwerfen, zu erstellen, zu dokumentieren und zu nutzen. Mit Swashbuckle können Sie Ihrem Web-API-Projekt ganz einfach Swagger-Dokumentation hinzufügen, indem Sie Ihren Code mit Attributen versehen, die Ihre API-Endpunkte, Parameter und Antworten beschreiben. Swashbuckle verwendet diese Informationen, um eine Swagger-JSON-Datei zu generieren, mit der wiederum eine interaktive API-Dokumentation sowie Client-SDKs und vieles mehr generiert werden können.
Es gibt drei Hauptkomponenten von Swashbuckle:
Swashbuckle.AspNetCore.Swagger: ein Swagger-Objektmodell und eine Swagger-Middleware, um SwaggerDocument-Objekte als JSON-Endpunkte verfügbar zu machen.
Swashbuckle.AspNetCore.SwaggerGen: ein Swagger-Generator, der SwaggerDocument-Objekte direkt aus Ihren Routen, Controllern und Modellen erstellt. Sie wird in der Regel zusammen mit der Swagger-Endpunktmiddleware verwendet, um Swagger-JSON automatisch verfügbar zu machen.
Swashbuckle.AspNetCore.SwaggerUI: eine eingebettete Version des Swagger UI-Tools. Damit wird Swagger-JSON interpretiert, um eine ansprechende, anpassbare Benutzeroberfläche zur Beschreibung der Web-API-Funktionen zu erstellen. Es enthält integrierte Testumgebungen für die öffentlichen Methoden.
Der folgende dotnet add-Befehl installiert das Swashbuckle NuGet-Paket:
dotnet add <name>.csproj package Swashbuckle.AspNetCore -v 6.5.0
Hinzufügen und Konfigurieren von Swagger-Middleware
Fügen Sie den Swagger-Generator zur Dienstsammlung in Program.cs hinzu.
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
Hinweis
Der im vorherigen Beispiel gezeigte Aufruf von AddEndpointsApiExplorer ist nur für minimale APIs erforderlich.
Aktivieren Sie die Middleware für die Bereitstellung des generierten JSON-Dokuments und der Benutzeroberfläche von Swagger ebenfalls in Program.cs:
app.UseSwagger();
if (app.Environment.IsDevelopment())
{
app.UseSwaggerUI();
}
Der Standardendpunkt für die Swagger-Benutzeroberfläche ist http:<hostname>:<port>/swagger.
Hinweis
SwaggerUI ist in Ihrer Entwicklungsumgebung sehr nützlich. Es kann in der Produktion aktiviert werden, aber Sie sollten alle Sicherheitsanforderungen für Ihre spezifische Anwendung berücksichtigen, bevor Sie dies tun.
Anpassen und Erweitern der Swagger-Dokumentation
Swagger bietet Optionen zum Dokumentieren des Objektmodells und Anpassen der Benutzeroberfläche. Die an die AddSwaggerGen-Methode übergebene Konfigurationsaktion kann in der OpenApiInfo-Klasse zusätzliche Informationen enthalten.
Das folgende Codebeispiel zeigt, wie Informationen hinzugefügt werden, die in der API-Dokumentation angezeigt werden.
// Add using statement for the OpenApiInfo class
using Microsoft.OpenApi.Models;
builder.Services.AddSwaggerGen(options =>
{
options.SwaggerDoc("v1", new OpenApiInfo
{
Version = "v1",
Title = "Fruit API",
Description = "API for managing a list of fruit their stock status.",
TermsOfService = new Uri("https://example.com/terms")
});
});
Die Swagger-Benutzeroberfläche zeigt die Version und die hinzugefügten Informationen an:
Sie können Vorgänge in Ihrer API mit der Option .WithTags gruppieren. Sie können auch beschreibenden Text hinzufügen, der den Vorgang mit der Option .WithSummary beschreibt. Der folgende Beispielcode zeigt die Verwendung von .WithTags zum Gruppieren des POST-Vorgangs in eine post-Gruppe (Beitrag) und eine fruit-Gruppe (Früchte). Außerdem wird dem Vorgang die in der Option .WithSummary angegebene Zusammenfassung hinzugefügt.
app.MapPost("/fruits", async (Fruit fruit, FruitDb db) =>
{
db.Fruits.Add(fruit);
await db.SaveChangesAsync();
return Results.Created($"/{fruit.Id}", fruit);
})
.Produces<Fruit>(201)
.WithTags("post", "fruits")
.WithSummary("Create a new fruit");
Die Benutzeroberfläche von Swagger zeigt die angegebene Gruppierungs- und Zusammenfassungsbeschreibung an.
