4 Optionen zum Ersetzen von Swagger in .NET 9 APIs

Einrichten eines Standard-API-Projekts

Tim beginnt mit der Erstellung eines minimalen API-Projekts in Visual Studio und wählt die Standardvorlage für ASP.NET Core Web API.

Er betont, dass das Kästchen zum Hinzufügen der OpenAPI-Unterstützung aktiviert werden muss, um sicherzustellen, dass Ihr Projekt die erforderliche OpenAPI-Dokumentengenerierung über einen JSON-Datei-Endpunkt enthält.

Sobald das Projekt läuft, navigiert Tim zur Standard-URL des OpenAPI-Dokuments (z. B. /swagger/v1/swagger.json), um die OpenAPI-Rohspezifikationen anzuzeigen. Diese Datei enthält strukturierte Metadaten über Ihre API-Endpunkte, einschließlich unterstützter Verben wie GET, POST und DELETE.

Obwohl sie funktional ist, merkt Tim an, dass die Anzeige des OpenAPI-Rohdokuments nicht benutzerfreundlich ist. Um eine bessere webbasierte Dokumentationsschnittstelle bereitzustellen, stellt er vier externe Tools vor, die die Erfahrung von Entwicklern und Kunden verbessern.

Option 1: Swagger UI - Die vertraute Erfahrung

Swagger UI ist immer noch ein sehr beliebtes Tool, auch wenn es nicht mehr standardmäßig enthalten ist. Tim demonstriert, wie man sie mit Hilfe des erforderlichen NuGet-Pakets dotnet zurückbringt: Swashbuckle.AspNetCore.SwaggerUI.

Nachdem er die Swagger-Benutzeroberfläche in einem neuen Projekt eingerichtet hat, konfiguriert er um 9:43 Uhr die Middleware mithilfe einer vereinfachten Syntax und setzt die Start-URL auf /swagger. Diese Benutzeroberfläche bietet eine benutzerfreundliche API-Dokumentationsschnittstelle, über die Entwickler Endpunkte anzeigen, Anforderungsparameter verstehen und sie im Browser testen können.

Swagger UI ist zwar inzwischen ein externes Tool, unterstützt aber nach wie vor die OpenAPI-Spezifikationen und ist nach wie vor eine der besten Wahl für grundlegende Dokumentationsanforderungen während der Entwicklung.

Option 2: ReDoc - Saubere, schreibgeschützte API-Dokumentation

Tims zweites Tool ist ReDoc, das Ihr OpenAPI-Dokument in eine ausgefeilte, schreibgeschützte HTML-Site verwandelt. Nachdem er das OpenAPI-Paket Swashbuckle.AspNetCore.ReDoc hinzugefügt hat, legt er die Dokumentation in /api/docs ab.

Im Gegensatz zu Swagger UI ermöglicht ReDoc keine Endpunkttests. Sie glänzt jedoch als webbasierte Dokumentationsschnittstelle, die für externe Benutzer und Kunden geeignet ist. Wenn Ihr Schwerpunkt ausschließlich auf der Definition von REST-APIs und der Darstellung strukturierter Dokumentation liegt, ist ReDoc die ideale Lösung.

Es ist erwähnenswert, dass ReDoc automatisch Inhalte auf der Grundlage der bereitgestellten OpenAPI-Spezifikationen generiert, die erwartete Antworten, Parameter und Datentypen umfassen. Dies passt gut zu Projekten, bei denen eine optimierte integrierte Unterstützung für die Dokumentation Vorrang vor Interaktivität hat.

Option 3: NSwag - Dokumentation + Codegenerierung

Als Nächstes geht Tim auf NSwag ein, ein flexibles und funktionsreiches Tool, das mehr kann als nur APIs zu dokumentieren - es kann auch Code für Clients in verschiedenen Sprachen wie C#, TypeScript und mehr generieren. Nach der Installation des NuGet-Pakets NSwag.AspNetCore richtet er die Swagger-ähnliche Schnittstelle ein, indem er sie auf denselben JSON-Endpunkt abbildet.

Tim erklärt, dass NSwag sowohl die Swagger-Spezifikationen als auch die OpenAPI-Standards unterstützt, so dass die Entwickler ihr bevorzugtes Format wählen können. Obwohl die Benutzeroberfläche Swagger ähnelt, sind es die externen Tool-Bibliotheken und die erweiterten Funktionen (wie die automatische Client-Erstellung), die NSwag auszeichnen.

Er weist darauf hin, dass die Fähigkeit von NSwag, Code zu generieren, hilfreich ist, um den manuellen Aufwand bei der Integration mit APIs zu reduzieren, insbesondere bei Projekten, die mehrere Dienste oder externe Tools umfassen. Es ist eine leistungsstarke Lösung für Teams, die eine robuste Client-Server-Kommunikation aufbauen.

Option 4: Scaler - Tims Favorit für API-Tests

Tim stellt Scaler UI als seinen persönlichen Favoriten unter allen Optionen vor und beschreibt es als eine Mischung aus Postman und Dokumentation im Browser. Nach dem Hinzufügen des Scaler.AspNetCore-Pakets ist nur eine Codezeile (app.MapScalerApiReference()) erforderlich, um die Schnittstelle zu aktivieren.

Scaler unterstützt volle Interaktivität, einschließlich der Ausführung von Anfragen mit Abfrageparametern, Headern und Cookies. Das Besondere daran ist das Echtzeit-Feedback: Antwortzeiten, Header und Ergebnisdaten werden sofort zurückgegeben.

Ein herausragendes Merkmal von Scaler ist seine Fähigkeit, Curl-Befehle und Client-Code-Schnipsel für verschiedene Sprachen zu generieren (PHP, Node, Python, C# über HttpClient und RestSharp). Tim findet dies besonders nützlich für das schnelle Kopieren und Einfügen von API-Aufrufen während der Entwicklung.

Scaler ermöglicht auch das Umschalten zwischen hellen und dunklen Modi, was es zu einer benutzerfreundlichen API-Dokumentationsplattform mit Raum für weitere Verbesserungen macht. Als Open-Source-API-Plattform entwickelt sich Scaler mit aktiver Wartung und starkem Interesse der Community ständig weiter.

Abschließende Überlegungen: Optionen bringen Flexibilität

In den letzten Minuten des Videos betont Tim, dass das Entfernen von Swagger UI aus .NET-Webvorlagen wie ein Rückschritt erscheinen mag, aber in Wirklichkeit eine Gelegenheit ist, moderne, maßgeschneiderte Lösungen zu nutzen. Diese Änderung steht im Einklang mit den schnellen Veröffentlichungszyklen von Microsoft, bei denen die Funktionen immer modularer und konzentrierter werden.

Die OpenAPI-Unterstützung fungiert jetzt eher als erstklassige Unterstützung als eine starre, native Implementierung. Es steht Ihnen frei, die Tools je nach den Anforderungen Ihres Projekts zu kombinieren - ob interaktive Tests mit Scaler, Client-Code-Generierung mit NSwag oder saubere Ausgabe mit ReDoc.

Tim ermutigt die Entwickler, diese Tools auszuprobieren und herauszufinden, welches zu ihrem Arbeitsablauf passt, und möglicherweise sogar mehrere Benutzeroberflächen für verschiedene Umgebungen zu verwenden (z. B. eine für die Entwicklung und eine andere für die öffentliche Dokumentation). Die Tatsache, dass alle diese Optionen die OpenAPI- und Swagger-Spezifikationen unterstützen, bedeutet, dass Sie nicht an einen einzigen Anbieter oder Arbeitsablauf gebunden sind.

Abschluss

Dank der Abschaffung von Swagger UI als Standard in .NET 9 haben Entwickler nun die Freiheit, das beste Tool für ihre OpenAPI-Dokumentation zu wählen. Ganz gleich, ob Sie HTTP-APIs dokumentieren, externe Tools bereitstellen oder die interne Entwicklung unterstützen, es gibt eine Lösung, die Ihren Zielen gerecht wird.

Mit Tools wie Swagger UI, ReDoc, NSwag und Scaler war das Dokumentieren und Testen von APIs noch nie so anpassbar und entwicklerfreundlich. Wie Tim Corey in seinem Video zeigt, braucht man nur ein paar Pakete, ein paar Zeilen Code und den Wunsch, die Tools zu erforschen, die Ihrer Anwendung und Ihrem Team am besten dienen.