Clients und Server-Stubs aus einem OpenAPI-Dokument generieren und generiert halten

Ziel

Typisierte Client-Bibliotheken und serverseitige Anfrage- und Antworttypen aus dem OpenAPI-Dokument ableiten, damit das Dokument der einzige Vertrag bleibt und handgeschriebener Code nicht unbemerkt von ihm abweichen kann.

Voraussetzungen

Ein validierendes OpenAPI-Dokument mit einer operationId auf jeder Operation: Die Spezifikation definiert sie als eindeutige Zeichenkette zur Identifizierung der Operation, die Werkzeuge zur Identifizierung von Operationen verwenden können, und Generatoren leiten daraus Methodennamen ab. Ein Generator, dessen Ausgabesprache man lesen kann; OpenAPI Generator führt Client- und Server-Generatoren pro Sprache auf. Eine Entscheidung, wo generierter Code liegt: im Repository committet oder während des Builds erzeugt.

Schritte

1. Die Generatorversion im Repository festlegen (ein Container-Image-Tag oder ein Wrapper-Skript). Die generierte Ausgabe ändert sich zwischen Generatorversionen, und ein nicht festgelegter Generator erzeugt unechte Diffs.
2. In ein eigenes Verzeichnis generieren, das nichts Handgeschriebenes enthält. Den genauen Befehl im Task-Runner hinterlegen, sodass alle, einschliesslich CI, auf die gleiche Weise neu generieren.
3. Konfigurieren statt bearbeiten: Die Nutzungsdokumentation listet --additional-properties für Generatoroptionen, --type-mappings für Typersetzungen und --template-dir für kopierte Vorlagen, wenn die Ausgabe strukturelle Änderungen braucht. Die Anpassungsdokumentation beschreibt .openapi-generator-ignore, nach dem Vorbild von .gitignore, als Möglichkeit, den Generator davon abzuhalten, aufgeführte Dateien zu überschreiben, etwa ein README oder einen von Hand gepflegten Wrapper.
4. Für Server nur Schnittstellen und Modelle generieren, sie in separaten Dateien implementieren und den Compiler jede Operation melden lassen, die fehlt oder deren Signatur sich geändert hat.
5. Für Clients den generierten Client in eine dünne, handgeschriebene Schicht einbetten, die Wiederholungsversuche, Authentifizierung und Logging hinzufügt, damit der generierte Teil vollständig ersetzt werden kann.
6. Einen CI-Job hinzufügen, der neu generiert und bei git diff --exit-code fehlschlägt, wenn die Ausgabe committet wird; wird sie nicht committet, den Build von diesem Generierungsschritt abhängig machen.
7. Bei jeder Änderung des Dokuments neu generieren, die Tests laufen lassen und den Diff des generierten Codes bei der Review lesen: er zeigt genau, welche Konsumenten betroffen sind.

Erwartetes Ergebnis

Das OpenAPI-Dokument ändert sich zuerst, und der Code folgt mechanisch; eine Vertragsänderung, die einen Konsumenten brechen würde, zeigt sich als Compile-Fehler oder Diff im generierten Code statt erst zur Laufzeit.

Grenzen und Prüfbasis

Generatoren decken die gängige Teilmenge der Spezifikation ab; komplexe oneOf-Schemas, Callbacks und ungewöhnliche Sicherheitsschemata können umständlichen oder falschen Code erzeugen, und die eigene Fehlerliste des Generators wird Teil der Abhängigkeit. Generierter Code ist ausführlich; der Umfang ist der Preis des Vertrags. Das Verfahren ist eine Synthese der zitierten Dokumentation, kein gemessener Vergleich.