Wer eine Spec hat, bekommt Dokumentation, Mocking, Client-Generierung und eine Testgrundlage automatisch mit.
Wer keine hat, pflegt alles manuell, was schnell veraltet. OpenAPI, frueher Swagger, ist der etablierte Standard zur Beschreibung von REST APIs in YAML oder JSON.
API-First mit OpenAPI
Den Vertrag zuerst zu definieren, bevor die Implementierung beginnt, erzwingt Designdiskussionen fruehzeitig, wo Aenderungen noch guenstig sind, statt spaeter, wo jede Aenderung ein Breaking Change fuer bestehende Clients ist.
Tooling rund um OpenAPI
Fuer die Dokumentation eignen sich Swagger UI oder Redoc, beide rendern aus der Spec eine interaktive Oberflaeche und lassen sich selbst hosten. Fuers Mocking generieren Werkzeuge wie Prism oder wiremock einen Mock-Server aus der Spec, mit dem Consumer-Entwickler arbeiten koennen, bevor der Provider fertig ist. Fuer Client-Generierung erzeugt openapi-generator API-Clients fuer dutzende Sprachen aus derselben Spec. Und auch Server-Stubs lassen sich generieren, in Symfony etwa ueber entsprechende Bundles direkt aus Annotations oder PHP-Attributes.
Die Spec aktuell halten
Entweder wird die Spec aus dem Code generiert, was Aktualitaet garantiert, aber Design-Entscheidungen an den Code bindet, oder sie wird manuell gepflegt, was API-First erlaubt, aber aktiv synchron gehalten werden muss.
Checkliste: OpenAPI Spec vorhanden und versioniert im Repository, Swagger UI oder Redoc fuer Entwickler zugaenglich, Mock-Server fuer Consumer-Entwickler eingerichtet, Spec automatisch auf Validitaet geprueft, Spec-Aktualitaet sichergestellt.
Ein Beispiel aus der Praxis
Eine API-Dokumentation wurde manuell in einem separaten Wiki gepflegt und war innerhalb weniger Monate erkennbar veraltet, weil niemand sie parallel zu Codeaenderungen aktualisierte. Partnerentwickler integrierten auf Basis falscher Angaben und wunderten sich ueber Fehler, die eigentlich laengst behobene Parameter betrafen. Nach der Umstellung auf eine aus Code-Annotations automatisch generierte OpenAPI-Spec war die Dokumentation zwangslaeufig immer so aktuell wie der Code selbst, ein einfacher struktureller Fix fuer ein wiederkehrendes Problem.
OpenAPI-Setup fuer eure API? markom.digital implementiert OpenAPI-Specs und richtet Tooling fuer Doku, Mocking und Client-Generierung ein.
