Azure API Management bietet Unterstützung für die OpenAPI-Spezifikation v3 (Vorschau), die neueste Version des verbreiteten Open-Source-Standards für das Beschreiben von APIs. Die Implementierung der Funktion basiert auf dem OpenAPI.NET SDK.

In diesem Blogbeitrag werden die folgenden Themen besprochen:

• die Vorteile der OpenAPI-Spezifikation für Ihre APIs
• das Erstellen von APIs mithilfe von OpenAPI-Spezifikationsdokumenten in Azure API Management
• das Exportieren von APIs als OpenAPI-Spezifikationsdokumente
• Handlungsbedarf bis zur allgemeinen Verfügbarkeit

Gründe für das Verwenden der OpenAPI-Spezifikation für Ihre APIs

Die OpenAPI-Spezifikation ist ein weit verbreiteter Industriestandard. Die OpenAPI Initiative wird von über 30 Unternehmen unterstützt, u. a. auch von großen Konzernen wie Microsoft.

Mit der OpenAPI-Spezifikation können Sie Ihre APIs von deren Implementierungen abstrahieren. API-Definitionen sind sprachunabhängig.

Sie sind leicht verständlich, aber dennoch genau. Ihre APIs werden von YAML- oder JSON-Dateien dargestellt, sodass sie sowohl von Menschen als auch von Computern gelesen werden können.

Durch die weite Verbreitung der OpenAPI-Spezifikation gibt es ein umfangreiches Toolingökosystem. Es gibt z. B. Tools, die die Zusammenarbeit beim Entwerfen von APIs erleichtern, oder Tools, die Client-SDKs und Serverimplementierungen in beliebten Programmiersprachen automatisch generieren.

Importieren von Definitionen der OpenAPI-Spezifikation v3 in Azure API Management

Wenn Ihre APIs in einer OpenAPI-Spezifikationsdatei definiert sind, können Sie sie ohne Probleme in Azure API Management importieren. Das Azure-Portal erkennt automatisch die richtige Version Ihrer OpenAPI-Spezifikationsdateien. Im Tutorial Importieren und Veröffentlichen Ihrer ersten API erfahren Sie, wie Sie Ihre APIs über die Benutzeroberfläche importieren können.

Alternativ können Sie APIs über einen REST-API-Aufruf importieren. Legen Sie dazu den contentFormat-Nutzlastparameter auf openapi, openapi+json oder openapi-link fest.

API Management wählt beim Importieren die erste HTTPS-URL aus, wenn das Feld servers (Server) der Spezifikation mehrere Einträge enthält. Wenn keine HTTPS-URLs vorhanden sind, wird die erste HTTP-URL ausgewählt. Wenn keine HTTP-URLs vorhanden sind, bleibt die Back-End-Dienst-URL leer.

Die Importfunktion ist eingeschränkt. Sie unterstützt z. B. nicht die Felder examples (Beispiele) und multipart/form-data (Multipart-/Formulardaten).

Exportieren von Definitionen der OpenAPI-Spezifikation v3 in Azure API Management

Mit Azure API Management können Sie Ihre APIs problemlos im Format der OpenAPI-Spezifikation v3 exportieren.

API-Spezifikationen können über das Entwicklerportal als JSON- oder YAML-Dateien heruntergeladen werden. Das Entwicklerportal ist eine automatisch generierte, komplett anpassbare Website, auf der sich Interessierte über APIs und deren Verwendung informieren und diese interaktiv ausprobieren können. Außerdem können sie sich registrieren, um API-Schlüssel zu erhalten.

Sie können die Spezifikationen auch über die Benutzeroberfläche des Azure-Portals oder einen REST-API-Aufruf exportieren. Legen Sie dazu den Formatabfrageparameter auf openapi-link fest.

Erste Schritte und geplante Änderungen

Sie können die aktuellen Funktionen innerhalb weniger Minuten ausprobieren. Importieren Sie dazu Ihre APIs aus den OpenAPI-Spezifikationsdateien. Vor der allgemeinen Verfügbarkeit dieses Features soll zudem das Exportieren im JSON-Format über einen REST-API-Aufruf implementiert werden. In den kommenden Monaten soll außerdem die Unterstützung für das Importieren und Exportieren mit der OpenAPI-Spezifikation v3 im PowerShell SDK hinzugefügt werden.

Teilen Sie uns Ihre Meinung mit.