Was ist OpenAPI 3.0? Nutzung und Vorteile
Sie haben eine Schnittstelle entwickelt und nun fragen Sie Ihre Kollegen ständig, was Sie vom Server als Antwort zu erwarten haben – und Sie dürfen es ihnen wiederholt erklären? Dadurch stockt der ganze Prozess? Eine gut dokumentierte Schnittstelle kann hier Abhilfe schaffen: Mit dem Standard OpenAPI 3.0 können Sie Ihre API-Schnittstellen managen und standardisieren. In diesem Blogbeitrag zeige ich Ihnen gute Gründe für den Einsatz des OpenAPI-3.0-Standards und wie genau es funktioniert.
Web-APIs bekommen einen immer höheren Stellenwert und sind in vielen Unternehmen nicht mehr wegzudenken. Aus diesem Grund erhöht sich auch immer weiter die Anzahl an APIs, die ein Unternehmen benutzt und verwaltet. Der daraus resultierende Verwaltungsaufwand drängt Sie und andere dazu, Schnittstellen zu managen. Mit der OpenAPI-Spezifikation können Sie RESTful-APIs standardisiert beschreiben.
Was ist OpenAPI?
OpenAPI ist ein Standard, der genutzt wird, um Anwendungsprogrammierschnittstellen oder APIs (aus dem Englischen „application programming interface“) zu beschreiben. Einer der heutigen Unterstützer dieses Standards ist die SAP SE. Die genauen Spezifikationen können Sie unter swagger.io/specification nachlesen.
Die größte Verwirrung um OpenAPI ist historisch bedingt: Der Standard OpenAPI ist aus dem Projekt „Swagger“ heraus entstanden. Eine Zeit lang war der Standard Teil von Swagger. Jedoch hat sich dieser seit der Version OpenAPI 3.0 von Swagger losgelöst. Kurz gesagt ist OpenAPI der Standard, mit dem Sie Schnittstellen beschreiben können. Im Gegensatz dazu ist Swagger eine Sammlung von Werkzeugen, um aus der standardisierten Dokumentation der API mit OpenAPI zu profitieren.
Vorteile
Der Vorteil von OpenAPI für Sie liegt darin, dass dieser als Standard von vielen verstanden wird und ein nicht triviales Thema deutlich vereinfacht. Folglich können Sie die Kommunikation zwischen Abteilungen optimieren. Weiter können Sie die Schnittstellendokumentation ohne gemeinsame Programmiersprache verbreiten. Ein weiterer Vorteil ist die Möglichkeit, interaktive Dokumentationen zu erstellen, indem die Schnittstellen mit wenig Aufwand und Implementierungswissen getestet werden können.
Aufbau des OpenAPI-Standards
Der Standard ist in 8 Objekte gegliedert und in der YAML oder JSON festgehalten. Zwei davon möchte ich näher beschreiben.
- Das erste Objekt ist das Info-Objekt: Damit können Sie die API mit allgemeinen Informationen beschreiben und Ihrem Nutzer mitteilen, wofür die API verwendet werden soll.
- Das zweite Objekt ist das Path-Objekt: In diesem können Sie die Pfade angeben, unter dem die einzelnen Services zur Verfügung gestellt werden. Nach dem Pfad wird die Schnittstelle, die darunter zu erreichen ist, beschrieben. Direkt nachfolgend, nach der Angabe des Pfades, wird die HTTP-Methode angegeben. Hier können Sie spezifische Angaben zu dem Service festhalten. Anschließend folgt der Body der Schnittstelle und die Antwort, welche der Nutzer erwarten kann. Nach der Methode können Sie noch für den selben Pfad andere Methoden anlegen.
OpenAPI anwenden
APIs werden mit YAML oder JSON beschrieben. Somit können Entwickler aus dem Front- und Backend zusammenarbeiten und diese Dokumentation erarbeiten. Auf der Seite editor.swagger.io können Sie mit einem Beispiel starten. Zuerst können Sie sich den Standard an einem Beispiel anschauen. Danach können Sie direkt ausprobieren, wie das Ergebnis aus der Verwendung von OpenAPI aussieht. Abschließend können Sie hier Ihre eigene API standardisiert anlegen und das Ergebnis Live betrachten und auch testen. Sie sind solchen Dokumentationen höchstwarscheinlich schon über den Weg gelaufen – der SAP Business Hub zum Beispiel verwendet eine ähnliche Darstellung Ihrer API-Dokumentation.
OpenAPI: Standard auf dem Vormarsch
OpenAPI konnte sich als Standard für die Industrie durchsetzen und wird voraussichtlich in Zukunft immer häufiger benutzt, um Schnittstellen zu beschreiben und zu entwickeln. Haben Sie Fragen zu Swagger-Lösungen und deren möglichen Einsatzszenarien in Ihrem Unternehmen? Dann schreiben Sie mir gerne!
