© StonePictures/Shutterstock.com
Kolumne: EnterpriseTales

Kolumne: EnterpriseTales


Nachdem wir uns in der Kolumne der Oktoberausgabe dem OpenTracing-Standard gewidmet haben, wollen wir uns jetzt die OpenAPI-Spezifikation und deren Integration in das MicroProfile näher anschauen. Wie immer geht es dabei nicht nur darum, welche technischen Möglichkeiten der Standard liefert. Vielmehr wollen wir die Praxistauglichkeit der Spezifikation und die möglichen Anwendungsszenarien kritisch beleuchten und die verschiedenen Alternativen gegeneinander abwägen.

Als Swagger und das Swagger-UI [1] vor Jahren aufkamen, fungierten sie als eine gute und einfache Möglichkeit, die damals ebenfalls recht neuen RESTful APIs zu dokumentieren. Schnell entwickelte sich Swagger zum De-Facto-Standard in Sachen API-Dokumentation.

Da war es nur konsequent, aus der Swagger-Spezifikation heraus einen offiziellen Standard zur API-Dokumentation zu entwerfen und zu etablieren. Die OpenAPI-Initiative [2] gründete sich und am 1. Mai 2017 wurde der Release Candidate 0 der OpenAPI-Spezifikation der Version 3.0 veröffentlicht. Der Entschluss, dem ersten Release die Versionsnummer 3.0 zu geben, fiel vor dem Hintergrund, dass zu diesem Zeitpunkt noch niemand abschätzen konnte, inwieweit der Standard von der Community angenommen werden würde. OpenAPI wurde im ersten Schritt lediglich als die Weiterentwicklung von Swagger gesehen, das zu diesem Zeitpunkt in Version 2 vorlag. Mittlerweile hat sich OpenAPI als Standard zur Dokumentation von APIs weitgehend etabliert, unabhängig davon, ob das API im Nachhinein dokumentiert wird (Code-First) oder bereits vor der Implementierung (Contract-First).

Code-First vs. Contract-First

Die Diskussion, ob es sinnvoll ist, zunächst mit dem Code zu starten und daraus dann die API-Dokumentation zu generieren, oder ob es nicht besser ist, die Schnittstelle vorher zu planen, die Dokumentation von Hand mit einem geeigneten Tool zu erzeugen und gegebenenfalls daraus den Code zu generieren, ist älter als OpenAPI und sogar älter als Swagger. Solche Diskussionen hat es bereits in der SOA-Welt gegeben, als Schnittstellen noch mit Hilfe von WSDLs spezifiziert wurden.

Damals wie heute bringen beide Varianten Vor- und Nachteile mit. Sicherlich existieren Mischformen. Beim initialen Aufsetzen der Schnittstelle hängt die Wahl des besten Vorgehens vom Projektkontext ab. Wenn Client und Server initial vom selben Team entwickelt werden, ist die Code-First-Variante normalerweise die Variante, mit der sich schneller Ergebnisse erzielen lassen. Wenn hingegen die Sch...

Neugierig geworden?

Angebote für Teams

Für Firmen haben wir individuelle Teamlizenzen. Wir erstellen Ihnen gerne ein passendes Angebot.

Das Library-Modell:
IP-Zugang

Das Company-Modell:
Domain-Zugang