OpenAPI (Swagger)

Was ist OpenAPI?

OpenAPI ist eine standardisierte, maschinenlesbare Art, eine REST-API zu beschreiben. Eine einzige Datei, in YAML oder JSON geschrieben, listet jeden Endpunkt, die Parameter, die er annimmt, die Form jeder Anfrage und Antwort, die geforderte Authentifizierung und die möglichen Fehler. Swagger war der ursprüngliche Name. Als die Spezifikation an die Linux Foundation übergeben wurde, wurde daraus OpenAPI, und der Name Swagger bezeichnet heute das Werkzeug rundherum.

Der Sinn ist eine einzige Quelle der Wahrheit, die Mensch und Maschine lesen können. Aus einem OpenAPI-Dokument lassen sich interaktive Dokumentation, Client-SDKs in einem Dutzend Sprachen, Server-Stubs, Mock-Server und Contract-Tests erzeugen. Zwei Teams können sich zuerst auf die Spezifikation einigen und dann Frontend und Backend parallel dagegen bauen. Eine Zahlungsintegration etwa lässt sich gegen einen erzeugten Mock verdrahten und testen, lange bevor der echte Dienst fertig ist.

Es gibt zwei Arbeitsweisen. Design-first heißt, Sie schreiben die Spezifikation von Hand und der Code folgt ihr. Code-first heißt, Sie annotieren Ihren Code und die Spezifikation wird daraus erzeugt. Design-first hält den Vertrag ehrlich, denn die API ist vereinbart, bevor sich jemand auf eine Implementierung festlegt. So oder so hört die Spezifikation auf, veraltende Dokumentation zu sein, und wird zu dem, woran das System geprüft wird.

OpenAPI bei Dallonses

Wir arbeiten API-first, und OpenAPI macht dieses Versprechen konkret. In den meisten Projekten existiert die Spezifikation, bevor es die Endpunkte gibt. Wir vereinbaren den Vertrag mit dem Kunden und seinen anderen Anbietern, erzeugen den Mock und die Doku und lassen Frontend- und Backend-Teams parallel arbeiten, ohne sich gegenseitig zu blockieren. Wenn die echte Implementierung kommt, prüfen Contract-Tests sie gegen dieselbe Spezifikation, sodass die ausgelieferte API jener entspricht, der alle zugestimmt haben.

Bei der API-Integration entscheidet ein klares OpenAPI-Dokument über den Unterschied zwischen einer sauberen Übergabe und wochenlangem Raten. Wir geben Kunden eine Spezifikation, die ihre eigenen Ingenieure lesen, in ihre Werkzeuge einbinden und der sie vertrauen können. Das bringt ein API-First-Ansatz: Systeme, die sauber zusammenkommen, weil der Vertrag aufgeschrieben und eingehalten wurde, nicht irgendwo in einem Thread beschrieben.

Bauen Sie eine API, der andere Teams vertrauen und an die sie sich anbinden müssen? Spezifizieren wir sie richtig.

Sprechen Sie mit uns über API-Design