OpenAPI als Vertrag zwischen AI-generiertem Frontend und Backend

Frontend und Backend entstehen selten gleichzeitig und selten von denselben Personen. Die Abstimmung dazwischen kostet in klassischen Projekten viel Zeit – und in AI-gestützten Projekten noch mehr, weil beide Seiten schneller Fakten schaffen. Ein maschinenlesbarer Vertrag ist eine der wenigen Maßnahmen, die dieses Problem wirklich auflösen.

1. Der klassische Reibungspunkt

Ohne verbindliche Beschreibung passiert immer dasselbe: Das Frontend rät die Feldnamen, das Backend ändert einen Datentyp, jemand findet den Fehler in der Integrationsphase. Bei generiertem Code beschleunigt sich das – ein Modell erfindet plausible Endpunkte mit plausiblen Feldern, die es so nie gab.

2. Warum ein Vertrag mehr ist als Doku

Der Unterschied zwischen Dokumentation und Vertrag ist die Verbindlichkeit. Eine OpenAPI-Beschreibung wird zum Vertrag, wenn sie drei Rollen erfüllt:

• Vorgabe für die Implementierung – nicht deren Abbild.
• Prüfgrundlage in der Pipeline: Abweichungen brechen den Build.
• Erzeugungsquelle für Client-Code, Typen, Mocks und Testdaten.

3. Contract-first oder generiert?

In der Praxis funktioniert eine Mischung am besten: Die Beschreibung wird aus einem expliziten Modell erzeugt – nicht aus zufälligen Implementierungsdetails – und gilt danach als verbindlich. Damit entfällt der Doppelaufwand, ohne dass die Schnittstelle zum Zufallsprodukt wird. Genau so ist es gemeint, wenn generierte OpenAPI-Dokumentation als Integrationskontext dient; siehe Feature-Seite.

4. Was eine gute Beschreibung enthält

Der Unterschied zwischen einer nutzbaren und einer nutzlosen Beschreibung liegt in Details, die oft fehlen:

• Fehlerfälle mit Statuscodes und Fehlerschema – nicht nur der Erfolgsfall.
• Pflichtfelder und Wertebereiche, nicht nur Typen.
• Beispiele je Endpunkt; sie sind für Menschen wie für Werkzeuge die schnellste Verständnishilfe.
• Authentifizierung und Berechtigungen, zumindest als Hinweis, welche Rolle einen Endpunkt nutzen darf.
• Paginierung, Sortierung, Filterung einheitlich beschrieben.
• Beschreibungstexte in ganzen Sätzen – sie sind der Teil, den ein Modell tatsächlich liest.

5. OpenAPI als Kontext für AI-Tools

Ein Coding Agent, der die Beschreibung zur Verfügung hat, muss nichts erfinden. Er kennt Endpunkte, Felder, Pflichtangaben, Fehlerfälle und Beispielantworten. Der praktische Effekt ist größer, als er klingt: Ein erheblicher Teil der Fehler in generiertem Integrationscode geht auf geratene Feldnamen und übersehene Fehlerpfade zurück.

Zwei Hinweise für die Praxis: Große Beschreibungen sollten ausschnittsweise bereitgestellt werden – der relevante Endpunkt statt 400 Seiten. Und die Beschreibung gehört ins Repository, damit sie ohne Netzzugriff verfügbar ist.

6. Contract-Tests

Ohne automatische Prüfung driften Vertrag und Implementierung auseinander – meist innerhalb weniger Wochen. Drei Prüfungen decken das Wesentliche ab:

# 1. The spec itself is valid and lint-clean.
openapi lint openapi.yaml

# 2. The implementation matches the spec (request/response schemas).
schemathesis run --checks all openapi.yaml --base-url http://localhost:8080

# 3. Breaking changes against the released spec fail the build.
openapi diff released/openapi.yaml openapi.yaml --fail-on-incompatible

Die Werkzeugnamen sind Beispiele; vergleichbare Prüfungen gibt es für alle verbreiteten Ökosysteme. Entscheidend ist, dass alle drei Schritte den Build brechen können.

7. Versionierung und Breaking Changes

Ein Vertrag ohne Versionsdisziplin ist ein Vertrag, den eine Seite jederzeit einseitig ändern kann. Bewährte Regeln:

• Additive Änderungen – neue optionale Felder, neue Endpunkte – sind unkritisch.
• Brechende Änderungen – entfernte oder umbenannte Felder, geänderte Typen, verschärfte Pflichtangaben – erfordern eine neue Version.
• Übergangszeit mit parallelem Betrieb beider Versionen, statt alle Konsumenten gleichzeitig umzustellen.
• Deprecation kennzeichnen, bevor entfernt wird.

8. Was ein Schema nicht ausdrückt

• Fachliche Regeln zwischen Feldern – „Enddatum nach Startdatum“ steht in keinem Typ.
• Zustandsabhängigkeit – welcher Aufruf in welcher Reihenfolge erlaubt ist.
• Berechtigungslogik auf Datensatzebene.
• Nicht-funktionale Zusagen wie Antwortzeiten oder Idempotenz-Garantien.

Diese Punkte gehören in Beschreibungstexte, Beispiele und – vor allem – in Tests. Ein Vertrag entbindet nicht davon, das Verhalten zu prüfen.

Checkliste: API als Vertrag

Fazit

OpenAPI ist keine Dokumentationspflicht, sondern das wirksamste Mittel gegen die teuerste Reibung in verteilten Teams. In AI-gestützter Entwicklung kommt ein zweiter Nutzen hinzu: Der Vertrag ist der Kontext, der verhindert, dass ein Modell Schnittstellen erfindet.

Der Aufwand ist überschaubar – eine gepflegte Beschreibung, drei Prüfungen in der Pipeline, eine Versionsregel. Der Ertrag zeigt sich in jeder Integrationsphase, die nicht stattfindet.