Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
OpenAPI Specification, früher Swagger genannt, beschreibt verschiedene Aspekte einer API. Eine OpenAPI-Spezifikation (Spezifikation) beschreibt die Endpunkte, Parameter und Antworten der API. OpenAPI-Spezifikationen werden in YAML oder JSON geschrieben und werden von Tools zum Generieren von Dokumentationen, Testfällen und Clientbibliotheken verwendet. Durch eine OpenAPI-Spezifikation können API-Generatoren sicherstellen, dass ihre API genau beschrieben, barrierefreier und einfacher in eine vielzahl von Anwendungen und Diensten integriert werden kann.
Hier erfahren Sie, warum Sie eine OpenAPI-Spezifikation für Ihre API verwenden sollten:
- Dokumentieren Sie eine API auf standardisierte Weise. Dokumentieren Sie eine API-Spezifikation in einem konsistenten und lesbaren Format.
- Generieren Sie ein Client-SDK. Verwenden Sie Tools wie Kiota , um die Generierung von Clientbibliotheken in verschiedenen Programmiersprachen zu automatisieren.
- Erstellen Sie eine simulierte API. Erstellen Sie Simulierte Server basierend auf der API-Spezifikation, die Ihnen während der frühen Entwicklungsphasen hilft, wenn die tatsächliche API noch nicht implementiert ist.
- Verbessern Sie die Zusammenarbeit. Stellen Sie verschiedene Teams (Front-End, Back-End, QA) mit einem klaren Verständnis der Funktionen und Einschränkungen der API bereit, wodurch neue Teammitglieder schnell auf dem Laufenden sind.
- Vereinfachen Sie Tests und Validierung. Automatisieren Sie die Validierung von API-Anforderungen und -Antworten anhand der Spezifikation, wodurch diskrepanzen leichter erkannt werden können.
- Mit API-Verwaltungstools integrieren. Einfache Integration, Bereitstellung und Überwachung Ihrer APIs mit vielen API-Verwaltungstools und Gateways, z. B. Azure API Center und Azure API Management.
- Vereinfachen der API-Gatewaykonfiguration. Verwenden Sie OpenAPI-Spezifikationen, um API-Gateways zu konfigurieren und Aufgaben wie Routing, Transformationen und einstellungen für die übergreifende Ressourcenfreigabe zu automatisieren.
Mithilfe von OpenAPI-Spezifikationen können Sie APIs erstellen, die gut entworfen und konsistent dokumentiert sind. Sie sind auch einfacher wartbar und sowohl intern als auch von externen Nutzern benutzerfreundlicher.
Sie haben noch keine OpenAPI-Spezifikation?
Das Schreiben einer Spezifikation von Hand für eine API, die bereits vorhanden ist, erfordert Zeit, und sie weicht davon ab, was die API tatsächlich tut. Eine weitere Option besteht darin, aufzuzeichnen, was die API zurückgibt, und die Spezifikation daraus zu generieren.
| Approach | Was Sie bekommen | Was zu beobachten ist |
|---|---|---|
| Schreiben Sie es von Hand | Vollständige Kontrolle über Beschreibungen und Beispiele | Es dauert Zeit, und es weicht von der echten API ab. |
| Generieren Sie aus Codeanmerkungen | Eine Spezifikation, die mit Ihrem Code synchronisiert bleibt | Sie benötigen Zugriff auf den API-Code, und das Framework muss den API-Zugriff unterstützen. |
| Generieren Sie es aus aufgezeichnetem Datenverkehr | Eine Spezifikation für jede API, die Sie aufrufen können, einschließlich solcher APIs, die Ihnen nicht gehören | Es deckt nur die Anfragen ab, die Sie erfasst haben. Üben Sie also die Teile der API aus, die Sie benötigen. |
Dev Proxy zeichnet die Anfragen und Antworten zwischen Ihrer App und einer API auf und generiert daraus eine OpenAPI-Spezifikation. Die Schritte finden Sie unter Generieren einer OpenAPI-Spezifikation.
Nächster Schritt
Zusammenarbeit auf GitHub
Die Quelle für diesen Inhalt finden Sie auf GitHub, wo Sie auch Issues und Pull Requests erstellen und überprüfen können. Weitere Informationen finden Sie in unserem Leitfaden für Mitwirkende.
