OpenAPI Generator ist ein Open-Source-Tool, das eine OpenAPI- oder Swagger-Spezifikation in funktionsfähigen Code umwandelt: Client-SDKs, Server-Stubs und Konfigurationsdateien. Sie installieren seine CLI, verweisen es auf Ihre Spezifikation, wählen einen Generator wie typescript-axios oder spring, und es schreibt den Code in einen Ausgabeordner. Dieser Leitfaden zeigt Ihnen, wie Sie es installieren, die verfügbaren Generatoren auflisten und Clients sowie Server für verschiedene Sprachen erstellen.
Was OpenAPI Generator ist
OpenAPI Generator liest eine maschinenlesbare API-Beschreibung und generiert daraus Quellcode. Geben Sie ihm eine openapi.yaml- (oder JSON-) Datei, und er kann eine Client-Bibliothek zum Aufrufen dieser API, einen Server-Stub, der sie implementiert, sowie Dokumentation und Konfiguration generieren.
Er unterstützt sowohl OpenAPI v2 (das ältere Swagger-Format) als auch OpenAPI v3. Das Projekt wird von der OpenAPITools-Organisation auf GitHub gepflegt und bietet Vorlagen für Dutzende von Sprachen und Frameworks.
Der entscheidende Unterschied: Dies ist ein Codegenerator, kein Dokumentationsgenerator. Dokumentationstools wie Swagger UI oder Redoc rendern Ihre Spezifikation in menschenlesbare HTML-Seiten. OpenAPI Generator hingegen produziert Code, den Sie kompilieren und ausliefern. Er kann auch Markdown-Dokumente generieren, aber seine Hauptaufgabe sind SDKs und Stubs.
Wie es sich zu Swagger Codegen verhält
Wenn Sie Swagger Codegen verwendet haben, wird sich OpenAPI Generator vertraut anfühlen. Es wurde im Mai 2018, zwischen den Swagger Codegen Versionen 2.3.1 und 2.4.0, von mehr als 40 seiner wichtigsten Mitwirkenden und Vorlagen-Ersteller von Swagger Codegen abgespalten.
Die Abspaltung erfolgte nach Meinungsverschiedenheiten über die Ausrichtung von Swagger Codegen 3.0.0. Die Community wollte einen schnelleren, offeneren Release-Zyklus. Die offiziellen Fork-Notizen beschreiben das Projekt als basierend auf Swagger Codegen 2.4.0-SNAPSHOT, sodass die beiden tiefe Wurzeln teilen. Wenn Sie die beiden abwägen, behandelt die Aufschlüsselung der Swagger Codegen Alternativen die praktischen Unterschiede.
Installation von OpenAPI Generator
Sie haben vier gängige Installationspfade. Wählen Sie den, der zu Ihrem Stack passt.
npm (am häufigsten)
Der npm-Wrapper ist für die meisten Teams der einfachste Einstiegspunkt. Er lädt das zugrunde liegende JAR herunter und verwaltet es für Sie.
npm install @openapitools/openapi-generator-cli -g
Sie können es auch ohne globale Installation ausführen:
npx @openapitools/openapi-generator-cli version
Homebrew (macOS)
brew install openapi-generator
Eigenständiges JAR
OpenAPI Generator ist eine Java-Anwendung, sodass Sie das JAR direkt von Maven Central herunterladen und mit Java ausführen können. Dies vermeidet die npm- oder Homebrew-Ebene vollständig.
wget https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/7.23.0/openapi-generator-cli-7.23.0.jar -O openapi-generator-cli.jar
java -jar openapi-generator-cli.jar help
Prüfen Sie Maven Central auf die neueste Versionsnummer vor dem Download.
Docker
Das offizielle Image ermöglicht es Ihnen, Code zu generieren, ohne etwas lokal zu installieren. Mounten Sie Ihr Arbeitsverzeichnis in den Container, damit es Ihre Spezifikation lesen und die Ausgabe zurückschreiben kann.
docker pull openapitools/openapi-generator-cli
docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli generate \
-i /local/openapi.yaml -g go -o /local/out/go
Auflistung der verfügbaren Generatoren
Bevor Sie etwas generieren, sehen Sie sich an, welche Generatoren existieren. Jeder Generator zielt auf eine Sprache plus Framework ab, wie java, python oder spring.
openapi-generator-cli list
Für eine kompakte, zeilenweise Ansicht verwenden Sie das Kurz-Flag und teilen nach Kommas auf:
openapi-generator-cli list -s | tr ',' '\n'
Die Liste trennt Client-Generatoren (zum Aufrufen einer API) von Server-Generatoren (zum Implementieren einer API) sowie Dokumentations- und Schema-Generatoren.
Generieren eines Client-SDK
Der Kernbefehl ist generate. Er benötigt drei Argumente, die Sie jedes Mal verwenden werden:
-i, --input-speczeigt auf Ihre Spezifikationsdatei oder URL.-g, --generator-namewählt aus, welcher Generator ausgeführt werden soll.-o, --outputlegt das Ausgabeverzeichnis fest.
Hier ist ein TypeScript-Client, der auf Axios basiert:
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client
Das schreibt einen typisierten Client in ./client. Jede Operation in Ihrer Spezifikation wird zu einer Methode, und jedes Schema wird zu einem Modell.
Dasselbe Muster funktioniert über Sprachen hinweg. Tauschen Sie den Generatornamen und den Ausgabeordner aus:
openapi-generator-cli generate -i openapi.yaml -g java -o ./client-java
openapi-generator-cli generate -i openapi.yaml -g python -o ./client-python
openapi-generator-cli generate -i openapi.yaml -g go -o ./client-go
Da der Code aus einer Spezifikation stammt, bleiben alle Clients konsistent mit dem Vertrag. Wenn sich die Spezifikation ändert, generieren Sie neu, und Ihre SDKs folgen.
Generieren von Server-Stubs
Server-Generatoren kehren die Richtung um. Anstelle von Code, der Ihre API aufruft, erhalten Sie ein Gerüst, das sie implementiert, mit Routing, Anforderungsmodellen und verbundenen Handler-Schnittstellen. Sie füllen die Geschäftslogik aus.
Hier ist ein Spring Boot Server-Stub:
openapi-generator-cli generate -i openapi.yaml -g spring -o ./server-spring
Das generierte Projekt liefert Ihnen Controller und DTOs, die Ihrer Spezifikation entsprechen. Sie implementieren die Schnittstellenmethoden, und die Anfrage- und Antwortstrukturen sind bereits für Sie definiert. Dies hält den laufenden Server im Einklang mit dem veröffentlichten Vertrag.
Ausgabe konfigurieren
Die Standardausgabe ist selten genau das, was Sie wollen. OpenAPI Generator bietet Ihnen mehrere Kontrollmöglichkeiten.
Zusätzliche Eigenschaften
Die meisten Generatoren legen sprachenspezifische Optionen über --additional-properties (Kurzalias -p) offen. Übergeben Sie diese als kommagetrennte Schlüssel=Wert-Paare:
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client \
--additional-properties=npmName=@acme/api-client,supportsES6=true,withSeparateModelsAndApi=true
Jeder Generator dokumentiert seine eigenen Eigenschaften. Überprüfen Sie daher die Generatorseite für die vollständige Liste der akzeptierten Schlüssel.
Eine Konfigurationsdatei
Wenn die Befehlszeile zu lang wird, verschieben Sie die Optionen in eine Konfigurationsdatei. JSON und YAML werden beide unterstützt.
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client -c config.yaml
Eine Konfigurationsdatei hält Ihre Generierungseinstellungen in der Versionskontrolle neben der Spezifikation, was Builds reproduzierbar macht.
Dateien ignorieren
OpenAPI Generator liest eine .openapi-generator-ignore-Datei im Ausgabeverzeichnis. Es verwendet dieselbe Syntax wie .gitignore. Verwenden Sie sie, um zu verhindern, dass der Generator manuell bearbeitete Dateien überschreibt.
# .openapi-generator-ignore
*.md
src/custom/**
Sie können mit --ignore-file-override <location> auf eine Ignorierungsdatei an einem anderen Speicherort verweisen.
Benutzerdefinierte Vorlagen
Jeder Generator wird von Mustache-Vorlagen gesteuert. Wenn die Standardausgabe nicht Ihrem Hausstil entspricht, kopieren Sie die Vorlagen, bearbeiten Sie sie und übergeben Sie Ihr Verzeichnis mit -t:
openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client \
-t ./my-templates
Dies ist das richtige Werkzeug, wenn Sie einen benutzerdefinierten Header, einen anderen HTTP-Client oder interne Namenskonventionen in jede generierte Datei integrieren müssen.
In CI ausführen
Codegenerierung gehört in Ihre Pipeline, nicht auf den Laptop eines einzelnen Entwicklers. Generieren Sie den Client bei jeder Spezifikationsänderung neu, damit das zugesagte SDK nie vom Vertrag abweicht. Hier ist ein GitHub Actions Schritt mit npx:
- name: Generate API client
run: npx @openapitools/openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client
Sie können den Build fehlschlagen lassen, wenn die neu generierte Ausgabe von dem abweicht, was zugesagt wurde, was Spezifikationen und SDKs erfasst, die nicht mehr synchron sind.
Die Spezifikation als einzige Quelle der Wahrheit beibehalten
OpenAPI Generator ist nur so gut wie die Spezifikation, die Sie ihm zuführen. Müll rein, Müll raus: eine vage oder ungültige Spezifikation erzeugt ein vages oder fehlerhaftes SDK. Der wertvollste Schritt geschieht also, bevor Sie jemals generate ausführen. Sie machen die Spezifikation korrekt, vollständig und stabil.
Hier passt Apidog. Apidog ist eine All-in-One-API-Plattform, die OpenAPI-nativ ist, sodass Ihre Designarbeit und Ihre Spezifikation dasselbe Artefakt sind. Sie entwerfen oder importieren die API, und Apidog hält das OpenAPI-Dokument als Quelle der Wahrheit, aus der alles andere resultiert.
Ein sauberer Workflow sieht so aus:
- Entwerfen oder importieren Sie die OpenAPI-Spezifikation in Apidog. Die Branch-Unterstützung ermöglicht es Ihnen, Änderungen isoliert zu bearbeiten, ähnlich der Versionskontrolle von OpenAPI mit Git.
- Validieren und linten Sie die Spezifikation, bevor Sie generieren. Eine Spezifikation, die einen OpenAPI Linter und einen Swagger Validator besteht, erzeugt saubereren Code mit weniger Überraschungen.
- Exportieren Sie die validierte Spezifikation und führen Sie sie dann dem OpenAPI Generator für Ihre SDKs und Stubs zu.
Sie können die Spezifikation auch mit Ihrem Repo synchron halten, zum Beispiel durch Synchronisieren der OpenAPI-Spezifikation mit GitHub, und Änderungen mit einem OpenAPI-Diff überprüfen, bevor sie ausgeliefert werden. Wenn Sie von älteren Tools weggehen, ist der Vergleich der Swagger-Alternativen für API-Design und -Tests ein guter Ausgangspunkt.
Wo Apidog aufhört und OpenAPI Generator beginnt
Es lohnt sich, hier präzise zu sein. Apidog generiert keine vollständigen Client-SDKs oder Server-Stubs. Das ist die Aufgabe von OpenAPI Generator, und die beiden sind komplementär statt konkurrierend.
Apidog bietet Ihnen jedoch fertige Client-Anfrage-Snippets für jeden Endpunkt, in vielen Sprachen und HTTP-Clients, zum Kopieren. Das sind anfragebasierte Beispiele, die Sie in ein Skript einfügen können, keine verpackten SDKs. Für eine generierte, versionierte Bibliothek oder ein Server-Gerüst führen Sie OpenAPI Generator auf der von Apidog produzierten Spezifikation aus.
Apidog liefert auch seinen eigenen Befehlszeilen-Testrunner, die Apidog CLI, die von der Codegenerierung getrennt ist. Sie führt Ihre API-Tests in CI aus; sie generiert keine SDKs. Installieren und verwenden Sie sie so:
npm install -g apidog-cli@latest
apidog run \
--access-token $APIDOG_ACCESS_TOKEN \
-t <testScenarioId> \
-e <envId> \
-r cli,html \
-n 1
Sie übergeben die Authentifizierung mit --access-token, -t wählt das Testszenario, -e wählt die Umgebung aus, gegen die ausgeführt werden soll, und -r wählt die Reporter aus. Führen Sie es auf einer aktuellen Node.js LTS-Version aus. Einzelheiten zur Einrichtung finden Sie im Apidog CLI Installationsleitfaden und der Anleitung zum Testen einer REST-API über die Befehlszeile.
Der vollständige Kreislauf ist also: Spezifikation in Apidog entwerfen und validieren, SDKs und Stubs mit OpenAPI Generator generieren, dann die laufende API mit der Apidog CLI überprüfen.
Testen Sie Apidog kostenlos, keine Kreditkarte erforderlich.
Häufig gestellte Fragen
Was ist OpenAPI Generator?
OpenAPI Generator ist ein Open-Source-Tool der OpenAPITools-Organisation, das Code aus einer OpenAPI- oder Swagger-Spezifikation generiert. Es produziert Client-SDKs, Server-Stubs, Dokumentation und Konfigurationsdateien und unterstützt sowohl OpenAPI v2 als auch v3.
Wie verwendet man OpenAPI Generator?
Installieren Sie die CLI (z. B. npm install @openapitools/openapi-generator-cli -g) und führen Sie dann generate mit drei Flags aus: -i für Ihre Spezifikation, -g für den Generator und -o für den Ausgabeordner. Führen Sie zuerst openapi-generator-cli list aus, um alle verfügbaren Generatoren anzuzeigen.
Wie funktioniert OpenAPI Generator?
Es parst Ihre Spezifikation in ein internes Modell und rendert dieses Modell dann mithilfe von Mustache-Vorlagen für Ihr gewähltes Ziel. Jede Operation wird zu einer Methode oder einem Handler, und jedes Schema wird zu einem typisierten Modell. Sie können die Vorlagen mit -t überschreiben, um die Ausgabe zu ändern.
Wie generiert man ein Client-SDK aus einer OpenAPI-Spezifikation?
Wählen Sie einen Client-Generator und führen Sie generate aus. Zum Beispiel erstellt openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client einen typisierten TypeScript-Client. Tauschen Sie typescript-axios gegen java, python oder go aus, um andere Sprachen anzusprechen.
Wie generiert man Server-Stubs?
Wählen Sie einen Server-Generator. Für ein Spring Boot Gerüst führen Sie openapi-generator-cli generate -i openapi.yaml -g spring -o ./server-spring aus. Die Ausgabe enthält Controller und Anforderungsmodelle aus Ihrer Spezifikation, und Sie implementieren die Handler-Logik.
Was ist der Unterschied zwischen OpenAPI Generator und Swagger Codegen?
OpenAPI Generator wurde im Mai 2018 von mehr als 40 seiner Mitwirkenden von Swagger Codegen abgespalten, die einen schnelleren, gemeinschaftsgetriebenen Release-Zyklus wollten. Die beiden teilen eine gemeinsame Basis, aber OpenAPI Generator hat jetzt seine eigene Roadmap, sein eigenes Generator-Set und seinen eigenen Release-Plan.
Wie generiert man ein PHP-SDK aus einer OpenAPI-Spezifikation?
Verwenden Sie den php-Generator: openapi-generator-cli generate -i openapi.yaml -g php -o ./client-php. Führen Sie openapi-generator-cli list aus, um den genauen Generatornamen zu bestätigen und um andere PHP-Framework-Optionen zu sehen, bevor Sie generieren.