OpenAPI/Swagger: Doku, Mocking, Client-Generierung.
OpenAPI/Swagger: Doku, Mocking, Client-Generierung
Eine OpenAPI-Spec ist nicht nur Dokumentation. Es ist der Vertrag, der alles andere ermöglicht.
Was OpenAPI ist und warum es zählt
OpenAPI (früher Swagger) ist ein Standard zur Beschreibung von REST APIs in YAML oder JSON. Wer eine OpenAPI-Spec hat, hat automatisch: Dokumentation, Mocking-Möglichkeiten, Client-Generierung, Testgrundlage.
Wer keine hat: muss alles manuell pflegen, was schnell veraltet.
API-First mit OpenAPI
Den Vertrag (OpenAPI Spec) definieren, bevor die Implementierung anfängt. Das erzwingt Designdiskussionen früh – wo es billig ist, Entscheidungen zu ändern. Nicht nachher, wo jede Änderung Breaking Change für existierende Clients ist.
Tooling um OpenAPI
Dokumentation: Swagger UI, Redoc. Beide nehmen die OpenAPI Spec und rendern interaktive API-Dokumentation. Kann selbst gehosted werden.
Mocking: Prism (Stoplight), wiremock. Aus der Spec wird ein Mock-Server generiert, den der Consumer-Entwickler nutzen kann, bevor der Provider fertig ist.
Client-Generierung: openapi-generator generiert API-Clients für dutzende Sprachen aus der Spec. TypeScript, PHP, Java – einmal Spec, viele Clients.
Server-Generierung: Auch Server-Stubs können generiert werden. In Symfony: nelmio/api-doc-bundle generiert OpenAPI aus Annotationen und PHP Attributes.
Spec aktuell halten
Die Spec ist nur so gut wie ihr Aktualitätsgrad. Ansätze: Spec aus Code generieren (Annotations/Attributes – Vorteil: immer aktuell, Nachteil: Design-Entscheidungen werden durch Code beeinflusst) oder Spec manuell pflegen (Vorteil: API-First möglich, Nachteil: muss aktiv synchron gehalten werden).
Checkliste OpenAPI
OpenAPI Spec vorhanden und versioniert im Repository
Swagger UI oder Redoc für Entwickler zugänglich
Mock-Server für Consumer-Entwickler eingerichtet
Spec automatisch auf Validität geprüft (in CI)
Spec-Aktualität sichergestellt (Code-generiert oder gepflegter Prozess)
OpenAPI-Setup für eure API?
markom.digital implementiert OpenAPI-Specs und richtet Tooling für Doku, Mocking und Client-Generierung ein.
