Dokumentieren einer ASP.Net Core-Web-API mit Swagger-Tools

  • 5 Minuten

Eine API kann sehr nützlich sein, an Bedeutung gewinnt sie aber erst, wenn die Entwickler*innen wissen, wie sie verwendet wird. Entwickler möchten eine API so schnell wie möglich integrieren. Mithilfe einer guten Dokumentation zur API kann sich ein Entwickler schnell einen Überblick über die Funktionen und Verwendung der API verschaffen, sodass die API effizient integriert werden kann.

In der Vergangenheit wurde die gesamte Dokumentation, in der eine API und deren Verwendung beschrieben wird, von Hand geschrieben. Nun verfügen wir über eine Standardspezifikation für API-Beschreibungen namens OpenAPI. Swagger UI bietet Tools zum Implementieren und Testen der OpenAPI-Spezifikation für Ihre APIs. Bei Swashbuckle handelt es sich um ein Open-Source-Paket, das eine automatische Erstellung von Beschreibungsdokumenten für OpenAPI direkt über die Web-API-Controller mithilfe der .NET-Reflexion bietet. Swashbuckle unterstützt Sie bei der Automatisierung des Beschreibungsprozesses, was es für Teams vereinfacht, auf OpenAPI basierende API-Dokumentationen zu erstellen, zu verwalten und zu verwenden. Sie beschreiben Ihre API und sorgen dafür, dass Tools eine ansprechende Dokumentation generieren.

Was ist OpenAPI?

Bei OpenAPI handelt es sich um eine Spezifikation zum Beschreiben von REST-APIs. Sie ist sprachunabhängig und ermöglicht die Beschreibung einer gesamten API mit den folgenden Elementen:

  • verfügbaren Endpunkten
  • Vorgangsparametern
  • Authentifizierungsmethoden
  • Kontakt- und anderen Informationen

API-Spezifikationen können in YAML oder JSON geschrieben werden. Dank OpenAPI-Spezifikation können Benutzer wie Computer die Funktionen einer API ohne Zugriff auf den entsprechenden Quellcode verstehen.

Was ist Swagger?

Bei Swagger handelt es sich um eine Reihe von Open-Source-Tools, die auf der OpenAPI-Spezifikation aufbauen. Mithilfe dieser Tools können Sie REST-APIs entwerfen, erstellen und dokumentieren. Swagger verwendet die OpenAPI-Spezifikation der API, um deren Struktur zu verstehen.

Swagger UI ist beispielsweise ein Tool, mit dem die Dokumentation für eine mit der OpenAPI-Spezifikation definierten API in einem Browser visuell gerendert werden kann. Swagger Codegen kann mithilfe derselben OpenAPI-Spezifikation einer API Client SDKs generieren.

Was ist Swashbuckle?

Swashbuckle ist eine Open-Source-Swagger-Implementierung, die zum Generieren von Swagger-Dokumentation für .NET Core-APIs mithilfe der .NET-Reflexion verwendet wird.

Swashbuckle besteht aus drei Hauptkomponenten:

  • Swashbuckle.AspNetCore.Swagger: Bei dieser Komponente handelt es sich um das Swagger-Objektmodell und die Middleware, mit der SwaggerDocument-Objekte als JSON-Endpunkte verfügbar gemacht werden.

  • Swashbuckle.AspNetCore.SwaggerGen: Bei dieser Bibliothek handelt es sich um einen Swagger-Generator, der direkt aus Ihren Routen, Controllern und Modellen SwaggerDocument-Objekte erstellt. Die Bibliothek wird in der Regel zusammen mit der Swagger-Endpunktmiddleware verwendet, um Swagger-JSON automatisch verfügbar zu machen.

  • Swashbuckle.AspNetCore.SwaggerUI: Bei diesem Paket handelt es sich um eine eingebettete Version des Tools Swagger UI. 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.

  • Swashbuckle-CLI: Nach der Installation ermöglicht Ihnen dieses globale .NET-Tool, OpenAPI-Spezifikationen während der Erstellung/Veröffentlichung zu generieren. Am Ende dieses Moduls finden Sie einen Link zum Herunterladen von Swashbuckle CLI.

Da diese Bibliotheken Ihrer App hinzugefügt werden, generieren und visualisieren sie Ihre API-Dokumentation aus der aktuellen Version Ihrer API. Damit wird eine dynamische Dokumentation erstellt, die immer mit dem aktuellen Code synchron ist.