Swagger UI zu .NET Aspire auf Linux hinzufügen

Installation des Swashbuckle NuGet-Pakets

[0:38 - 1:35] Tim öffnet das Tiny Ticket-Projekt in VS Code und navigiert zum API-Dienst's Program.cs. Die API hat bereits einen GET /api/tickets-Endpunkt aus der vorherigen Episode, aber dessen Aufruf erforderte das manuelle Erstellen der URL. Um eine geeignete Testoberfläche hinzuzufügen, ist der erste Schritt die Installation des Swagger UI-Pakets.

Rechtsklicken Sie auf das API-Projekt, wählen Sie "NuGet-Paket hinzufügen" und suchen Sie nach Swashbuckle.AspNetCore.SwaggerUI. Tim installiert die neueste Version (10.1.7 zum Zeitpunkt der Aufnahme). Nach der Installation erscheint der Paketverweis in der Projektdatei. Keine anderen Abhängigkeiten sind erforderlich, da das Projekt bereits OpenAPI-Unterstützung über die Standard-Aspire-Dienstkonfiguration enthält.

// Verify the package was added to the .csproj
// <PackageReference Include="Swashbuckle.AspNetCore.SwaggerUI" Version="10.1.7" />

// Verify the package was added to the .csproj
// <PackageReference Include="Swashbuckle.AspNetCore.SwaggerUI" Version="10.1.7" />

Swagger UI in Program.cs konfigurieren

[1:35 - 3:12] Nach der Installation des Pakets geht die Konfiguration in den nur für die Entwicklung vorgesehenen Block von Program.cs. Das Projekt hat bereits app.MapOpenApi() registriert, das die OpenAPI-Spezifikationsdatei zur Laufzeit generiert. Swagger UI muss lediglich wissen, wo sich diese Datei befindet und wie die Endpunktgruppe zu beschriften ist.

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();

    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/openapi/v1.json", "Ticket App API v1");
    });
}

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();

    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/openapi/v1.json", "Ticket App API v1");
    });
}

Der SwaggerEndpoint-Aufruf verweist auf die OpenAPI-Spezifikation, die .NET automatisch generiert. Der zweite Parameter ist ein Anzeigename, der im Dropdown-Menü von Swagger UI angezeigt wird. Tim betont, dass diese drei Zeilen die gesamte Swagger-Einrichtung sind. Sie könnten mehr Konfiguration hinzufügen, um die UI anzupassen, Endpunkte zu gruppieren oder Authentifizierungsheader hinzuzufügen, aber für ein Entwicklungstesttool sind die Standardwerte ausreichend.

Ein erwähnenswerter Punkt: Seit .NET 9 enthalten neue API-Projekte standardmäßig kein Swagger mehr. Microsoft hat die Zuständigkeiten getrennt, indem es OpenAPI als Standard bereitstellt und es Entwicklern überlässt, ihre bevorzugte UI-Schicht auszuwählen. Swagger, Scalar und andere Tools nutzen alle dieselbe OpenAPI-Spezifikationsdatei, sodass Sie nicht an einen bestimmten Viewer gebunden sind.

Ausführen und Überprüfen der Swagger-Oberfläche

[3:12 - 6:07] Nach dem Speichern startet Tim das Projekt über das Ausführen- und Debugfenster. Sobald das Aspire-Dashboard geladen ist und der API-Dienst als laufend angezeigt wird, navigiert er zur URL der API und fügt /swagger zum Pfad hinzu.

Die Swagger UI wird mit dem Label "Ticket App API v1" geladen und listet die verfügbaren Endpunkte auf. Der Root-Endpunkt (/) gibt eine einfache Statusnachricht zurück, und /api/tickets gibt die Ticketdaten aus der Datenbank zurück.

Tim klickt auf "Try it out" beim Root-Endpunkt und führt ihn aus. Die Antwort kommt mit einem 200-Status und einer Bestätigungsnachricht zurück. Dann wechselt er zum /api/tickets-Endpunkt und drückt auf Ausführen, was der Ausgangspunkt für die Fehlersuche ist.

Der erste Versuch schlägt mit einem Verbindungsfehler fehl: "Es trat ein netzwerkbezogener oder instancespezifischer Fehler auf, als die Verbindung zum SQL-Server hergestellt wurde." Der Datenbankcontainer hatte nach einem Rechnerneustart nicht gestartet. Tim opens Portainer, finds the SQL Server Docker container, and starts it. Nachdem der Container die Initialisierung abgeschlossen hat, kehrt er zu Swagger zurück und führt die Anfrage erneut aus. Dieses Mal wird die Antwort mit einem 200 zurückgegeben, mit den drei Testtickets, die in der Datenbank gespeichert sind.

Diese Sequenz erinnert praktisch daran, dass Integrationstests gegen die reale Infrastruktur Probleme aufdecken, die Unit-Tests und simulierte Daten nicht können. Der Datenbankcontainer ist nicht so konfiguriert, dass er beim Start automatisch startet, was bedeutet, dass der erste API-Aufruf nach einem Neustart fehlschlägt, es sei denn, Sie überprüfen zuerst den Containerzustand.

Was kommt als Nächstes: CRUD-Endpunkte

[6:07 - 7:20] Tim gibt einen Ausblick auf die kommenden Episoden der Serie. Die Tiny Ticket-API hat derzeit nur den GET /api/tickets-Endpunkt, der auf die gespeicherte Prozedur spTickets_GetAll verweist. Die übrigen gespeicherten Prozeduren in der Datenbank (Get by ID, Insert, Update, Delete) benötigen jeweils einen entsprechenden API-Endpunkt mit dem richtigen HTTP-Verb: GET für Abruf, POST für Erstellung, PUT für Aktualisierungen und DELETE für Entfernung.

Er merkt an, dass jeder Endpunkt demselben Muster folgt und einfach zu implementieren ist, aber die kommenden Videos werden sie einzeln behandeln, so dass jedes Teil unabhängig leicht referenziert werden kann. Die Entscheidung, die Serie in kleine, fokussierte Episoden zu unterteilen, bedeutet, dass Sie direkt zu dem benötigten Endpunkttyp springen können, ohne in einem längeren Video zu suchen.

Abschluss

[7:20 - 7:24] Das Hinzufügen von Swagger UI zu einem .NET Aspire-Projekt auf Linux erfordert ein NuGet-Paket und drei Zeilen Konfiguration in Program.cs. Die OpenAPI-Spezifikationsdatei wird bereits durch das Standard-Aspire-Dienst-Setup generiert, sodass Swagger nur einen Verweis auf diese Datei und einen Anzeigenamen benötigt. Von dort aus ist jeder Endpunkt in der API über den Browser testfähig, ohne dass ein separater Client gebaut werden muss.

Das Datenbankverbindungsproblem, dem Tim nach dem Neustart begegnete, unterstreicht einen praktischen Punkt: Wenn Ihr Entwicklungs-Stack Container umfasst, überprüfen Sie, ob sie laufen, bevor Sie API-Endpunkte testen. Swagger bietet Ihnen eine schnelle Feedback-Schleife für diese Überprüfung.

Seriennavigation: Dieser Artikel ist Teil der C# auf Linux-Serie, die die Tiny Ticket-App erstellt. Vorherige: Setup von .NET Aspire auf Linux. Nächster Schritt: Hinzufügen eines Get By ID Endpunkts.

Beispieltipp: Wenn Sie einen anderen OpenAPI-Viewer gegenüber Swagger bevorzugen, installieren Sie ein Paket wie Scalar oder RapiDoc und richten Sie es auf denselben /openapi/v1.json-Endpunkt aus. Die Spezifikationsdatei ist UI-agnostisch, sodass Sie Viewer austauschen können, ohne Ihre API-Konfiguration zu ändern.

Sehen Sie sich das vollständige Video auf seinem YouTube-Kanal an und gewinnen Sie mehr Einblicke in den Aufbau von APIs in der C# auf Linux-Serie.