Swagger-Codegen
Swagger
Dies ist das Swagger Codegen-Projekt, das die automatische Generierung von API-Client-Bibliotheken (SDK-Generierung), Server-Stubs und Dokumentation anhand einer OpenAPI-Spezifikation ermöglicht.
Wenn Sie einen Beitrag leisten möchten, beachten Sie bitte die Richtlinien und eine Liste der offenen Aufgaben.
Weitere Informationen finden Sie auf der Wiki-Seite und in den FAQ.
⚠️ Dieses Dokument bezieht sich auf Version 2.X. Suchen Sie hier nach Version 3.X.
Sowohl die Versionslinien 2.X als auch 3.X von Swagger Codegen sind verfügbar und werden unabhängig voneinander gepflegt.
HINWEISE:
Die Versionen 2.X ( io.swagger ) und 3.X ( io.swagger.codegen.v3 ) haben unterschiedliche Gruppen-IDs.
OpenAPI 3.0.X wird erst ab der 3.X-Version unterstützt.
Vollständige Informationen zur Versionierung finden Sie in der Versionierungsdokumentation.
Derzeit werden folgende Sprachen/Frameworks unterstützt:
API-Clients : ActionScript , Ada , Apex , Bash , C# (.net 2.0, 3.5 oder höher), C++ (cpprest, Qt5, Tizen), Clojure , Dart , Elixir , Elm , Eiffel , Erlang , Go , Groovy , Haskell (http -client, Servant), Java (Jersey1.x, Jersey2.x, OkHttp, Retrofit1.x, Retrofit2.x, Feign, RestTemplate, RESTEasy, Vertx, Google API Client Library für Java, Rest-assured), Kotlin , Lua , Node.js (ES5, ES6, AngularJS mit Google-Closure-Compiler-Anmerkungen) Objective-C , Perl , PHP , PowerShell , Python , R , Ruby , Rust (Rust, Rust-Server), Scala (Akka, http4s, swagger-async- httpclient), Swift (2.x, 3.x, 4.x, 5.x), Typescript (Angular1.x, Angular2.x, Fetch, jQuery, Node)
Server-Stubs : Ada , C# (ASP.NET Core, NancyFx), C++ (Pistache, Restbed), Erlang , Go , Haskell (Servant), Java (MSF4J, Spring, Undertow, JAX-RS: CDI, CXF, Inflector, RestEasy , Play Framework, PKMST), Kotlin , PHP (Lumen, Slim, Silex, Symfony, Zend Expressive), Python (Flask), NodeJS , Ruby (Sinatra, Rails5), Rust (Rust-Server), Scala (Finch, Lagom, Scalatra)
API-Dokumentationsgeneratoren : HTML , Confluence Wiki
Konfigurationsdateien : Apache2
Andere : JMeter
Weitere Informationen zum OpenAPI-Projekt finden Sie in OpenAPI-Spec.
Versionierung
Kompatibilität
Erste Schritte
Generatoren
So generieren Sie eine Beispiel-Client-Bibliothek
Generieren von Bibliotheken von Ihrem Server
Validierung Ihrer OpenAPI-Spezifikation
Generieren einer dynamischen HTML-API-Dokumentation
Generieren einer statischen HTML-API-Dokumentation
Workflow-Integration
Online-Generatoren
Beitrag
Swagger Codegen-Kernteam
Die OpenAPI-Spezifikation wurde seit ihrer ersten Erstellung im Jahr 2010 drei Revisionen unterzogen. Die aktuellen stabilen Versionen des Swagger Codegen-Projekts weisen die folgenden Kompatibilitäten mit der OpenAPI-Spezifikation auf:
| Swagger Codegen-Version | Veröffentlichungsdatum | Swagger/OpenAPI Spec-Kompatibilität | Notizen |
|---|---|---|---|
| 3.0.62 ( aktuell stabil ) | 27.08.2024 | 1,0, 1,1, 1,2, 2,0, 3,0 | Tag v3.0.62 |
| 2.4.43 ( aktuell stabil ) | 09.08.2024 | 1,0, 1,1, 1,2, 2,0 | Tag v2.4.42 |
Hier ist auch ein Überblick darüber, was als nächstes kommt:
| Swagger Codegen-Version | Veröffentlichungsdatum | Swagger/OpenAPI Spec-Kompatibilität | Notizen |
|---|---|---|---|
| 3.0.63-SNAPSHOT (aktuelle Version 3.0.0, bevorstehende Nebenversion) SNAPSHOT | Noch offen | 1,0, 1,1, 1,2, 2,0, 3,0 | Kleinere Veröffentlichung |
| 2.4.44-SNAPSHOT (aktueller Master, kommende Nebenversion) SNAPSHOT | Noch offen | 1,0, 1,1, 1,2, 2,0 | Kleinere Veröffentlichung |
Eine detaillierte Aufschlüsselung aller Versionen finden Sie in der vollständigen Kompatibilitätsliste.
Um mit Swagger Codegen loszulegen, lesen Sie die folgenden Anleitungen und Anweisungen:
Voraussetzungen
Gebäude
Mit Docker
Sobald Sie Ihre Umgebung eingerichtet haben, können Sie mit der Generierung von Clients und/oder Servern beginnen.
Um als kurzes Beispiel einen PHP-Client für https://petstore.swagger.io/v2/swagger.json zu generieren, können Sie Folgendes ausführen:
Git-Klon https://github.com/swagger-api/swagger-codegencd swagger-codegen
mvn sauberes Paket
java -jar module/swagger-codegen-cli/target/swagger-codegen-cli.jar generieren
-i https://petstore.swagger.io/v2/swagger.json
-l php
-o /var/tmp/php_api_clientHinweis: Wenn Sie Windows verwenden, ersetzen Sie den letzten Befehl durch
java -jar moduleswagger-codegen-clitargetswagger-codegen-cli.jar generieren -i https://petstore.swagger.io/v2/swagger.json -l php -o c:tempphp_api_client
Sie können die JAR (neueste Version) auch direkt von maven.org herunterladen
Um eine Liste der verfügbaren allgemeinen Optionen zu erhalten, können Sie Folgendes ausführen:
java -jar module/swagger-codegen-cli/target/swagger-codegen-cli.jar helfen beim Generieren
Um eine Liste der von PHP angegebenen Optionen zu erhalten (die mit einer Konfigurationsdatei über die Option -c an den Generator übergeben werden können), führen Sie bitte Folgendes aus
java -jar module/swagger-codegen-cli/target/swagger-codegen-cli.jar config-help -l php
Sie können einen Client für die Swagger-Beispiel-Petstore-API wie folgt erstellen:
./bin/java-petstore.sh
(Führen Sie unter Windows stattdessen .binwindowsjava-petstore.bat aus.)
Dadurch wird der Generator mit diesem Befehl ausgeführt:
java -jar module/swagger-codegen-cli/target/swagger-codegen-cli.jar generieren -i https://petstore.swagger.io/v2/swagger.json -l Java -o Proben/Client/Petstore/Java
mit einer Reihe von Optionen. Sie können die Optionen mit dem Befehl help generate abrufen (unten werden nur Teilergebnisse angezeigt):
NAME
swagger-codegen-cli generate - Generate code with chosen lang
SYNOPSIS
swagger-codegen-cli generate
[(-a | --auth )]
[--additional-properties ...]
[--api-package ] [--artifact-id ]
[--artifact-version ]
[(-c | --config )]
[-D ...] [--git-repo-id ]
[--git-user-id ] [--group-id ]
[--http-user-agent ]
(-i | --input-spec )
[--ignore-file-override ]
[--import-mappings ...]
[--instantiation-types ...]
[--invoker-package ]
(-l | --lang )
[--language-specific-primitives ...]
[--library ] [--model-name-prefix ]
[--model-name-suffix ]
[--model-package ]
[(-o | --output )]
[--release-note ] [--remove-operation-id-prefix]
[--reserved-words-mappings ...]
[(-s | --skip-overwrite)]
[(-t | --template-dir )]
[--type-mappings ...] [(-v | --verbose)]
OPTIONS
-a , --auth
adds authorization headers when fetching the swagger definitions
remotely. Pass in a URL-encoded string of name:header with a comma
separating multiple values
...... (results omitted)
-v, --verbose
verbose mode Anschließend können Sie den Client kompilieren und ausführen sowie Komponententests dafür durchführen:
CD-Beispiele/Client/Petstore/Java mvn-Paket
Auch in anderen Sprachen gibt es Beispiele für Zoohandlungen:
./bin/android-petstore.sh ./bin/java-petstore.sh ./bin/objc-petstore.sh
Es ist genauso einfach: Verwenden Sie einfach das Flag -i , um auf einen Server oder eine Datei zu verweisen.
? Swagger Codegen bietet eine Menge Flexibilität, um Ihre Präferenzen bei der Codegenerierung zu unterstützen. Schauen Sie sich die Generatordokumentation an, die Sie durch einige der Möglichkeiten führt und zeigt, wie Sie aus lokalen Dateien generieren und Dateiformate ignorieren.
Möglicherweise möchten Sie nicht alle Modelle in Ihrem Projekt generieren. Ebenso möchten Sie möglicherweise, dass nur eine oder zwei APIs geschrieben werden. Wenn dies der Fall ist, überprüfen Sie die Anweisungen zur selektiven Generierung.
Es gibt verschiedene Aspekte der Anpassung des Codegenerators, die über das bloße Erstellen oder Ändern von Vorlagen hinausgehen. Jede Sprache verfügt über eine unterstützende Konfigurationsdatei, um verschiedene Typzuordnungen zu verarbeiten oder Ihre eigenen Modelle bereitzustellen. Weitere Informationen finden Sie in den erweiterten Konfigurationsdokumenten.
Sie haben Optionen. Am einfachsten ist es, unseren Online-Validator zu verwenden, mit dem Sie nicht nur Ihre Spezifikation validieren können, sondern mit dem Debug-Flag auch sehen können, was mit Ihrer Spezifikation nicht stimmt. Schauen Sie sich zum Beispiel Swagger Validator an.
Wenn Sie die Validierung direkt auf Ihrem eigenen Computer durchführen möchten, ist Spectral eine hervorragende Option.
Verwenden Sie dazu einfach das Flag -l dynamic-html beim Lesen einer Spezifikationsdatei. Dadurch entsteht eine HTML-Dokumentation, die als Single-Page-Anwendung mit AJAX verfügbar ist. So zeigen Sie die Dokumentation an:
CD-Beispiele/dynamic-html/ npm installieren Knoten.
Dadurch wird ein node.js-Server gestartet, damit die AJAX-Aufrufe an einen Ort gelangen.
Verwenden Sie dazu beim Lesen einer Spezifikationsdatei einfach das Flag -l html . Dadurch wird eine einzelne, einfache HTML-Datei mit eingebettetem CSS erstellt, sodass Sie sie als E-Mail-Anhang versenden oder aus Ihrem Dateisystem laden können:
CD-Beispiele/html/ Öffnen Sie index.html
Es ist möglich, Swagger Codegen direkt in Ihren bevorzugten CI/CD-Workflows zu nutzen, um Ihre Anforderungen an die automatische Generierung zu optimieren. Sehen Sie sich den Workflow-Integrationsleitfaden an, um Informationen zu unseren Maven-, Gradle- und GitHub-Integrationsoptionen zu erhalten. ?
Wenn Sie keine eigene Instanz zur Codegenerierung ausführen und hosten möchten, lesen Sie unsere Informationen zu unseren Online-Generatoren.
Bitte beachten Sie diese Seite
Mitglieder des Swagger Codegen-Kernteams sind Mitwirkende, die regelmäßig wichtige Beiträge zum Projekt leisten (Probleme überprüfen, Fehler beheben, Verbesserungen vornehmen usw.).
Die Mitglieder des Kernteams übernehmen folgende Aufgaben:
Bietet anderen Benutzern Anleitung und Anleitung
Überprüft Pull-Anfragen und Probleme
Verbessert den Generator, indem er Verbesserungen vornimmt, Fehler behebt oder Dokumentationen aktualisiert
Legt die technische Richtung des Generators fest
Bitte melden Sie alle sicherheitsrelevanten Probleme oder Schwachstellen per E-Mail an [email protected], anstatt den öffentlichen Issue-Tracker zu verwenden.
Das Swagger Codegen-Projekt ist als Nutzen für Benutzer der Swagger/Open API Specification gedacht. Das Projekt selbst verfügt über die angegebene Lizenz. Bitte haben Sie außerdem Verständnis für die folgenden Punkte:
Die in diesem Projekt enthaltenen Vorlagen unterliegen der Lizenz.
Generierter Code unterliegt bewusst nicht der übergeordneten Projektlizenz
Wenn aus diesem Projekt Code generiert wird, gilt dieser als IS IS und als Eigentum des Benutzers der Software. Es gibt keine Garantien – weder ausdrücklich noch stillschweigend – für den generierten Code. Sie können damit machen, was Sie wollen, und sobald er generiert ist, liegt der Code in Ihrer Verantwortung und unterliegt den Lizenzbedingungen, die Sie für angemessen halten.
Wir möchten allen, die zu Swagger Codegen beigetragen haben, ein großes Lob aussprechen, sei es durch die Meldung von Problemen, die Behebung von Fehlern, die Erstellung von Vorlagen oder die Erstellung nützlicher Inhalte, von denen andere profitieren können.
