Verwenden von Swashbuckle zum Erstellen eines OpenAPI-Dokuments

Bevor eine Web-API in Azure API Management mit Visual Studio veröffentlicht werden kann, sollte sie über ein OpenAPI-Beschreibungsdokument verfügen.

Das OpenAPI-Dokument wird von API Management verwendet, um die Endpunkte für die Web-API zu ermitteln. Mithilfe der Swashbuckle-Tools ist es für VanArsdel-Entwickler einfacher denn je, eine OpenAPI-Beschreibung ihrer Web-APIs zu erstellen.

Was ist ein OpenAPI-Dokument, und welche Funktion hat es?

Das OpenAPI-Dokument definiert eine standard- und programmiersprachenunabhängige Schnittstellenbeschreibung für Web-APIs. Es ermöglicht sowohl Menschen als auch Computern, die Funktionen eines Diensts zu ermitteln und zu verstehen, ohne Zugriff auf Quellcode, zusätzliche Dokumentation oder eine Überprüfung des Netzwerkdatenverkehrs zu erfordern.

Das OpenAPI-Dokument ist ein Vertrag für Web-APIs. Es enthält alles, was eine verbrauchende Anwendung zum Verstehen der Web-APIs und Kommunizieren mit ihnen benötigt, ohne dass sie wissen muss, wo sich die APIs befinden oder ob sie ausgeführt werden.

Generieren eines OpenAPI-Dokuments aus einer ASP.NET Core-Web-API-Anwendung

Es gibt mehrere Möglichkeiten, das OpenAPI-Dokument aus Ihrer ASP.NET Core-Web-API-App zu generieren. Swashbuckle ist die gängigste Methode, dies zu tun.

Es ist einfach zu verwenden und zeigt nach der Installation in Ihrer App automatisch den Bildschirm der Swagger-Benutzeroberfläche an.

Swashbuckle generiert auch sofort das OpenAPI-Dokument, das alle API-Endpunktdetails, Nutzdatenstrukturen, Sicherheitsanforderungen usw. enthält. Hier ist das Beispieldokument für die Web-API von VanArsdel zur Bestandsverwaltung.

In der nächsten Lektion wird in einer Übung gezeigt, wie Sie diese OpenAPI-Funktion für Ihre ASP.NET Core-Web-API-App aktivieren.