codegen fanfaron
Swagger
Il s'agit du projet Swagger Codegen, qui permet la génération automatique de bibliothèques client API (génération SDK), de stubs de serveur et de documentation avec une spécification OpenAPI.
Si vous souhaitez contribuer, veuillez vous référer aux lignes directrices et à la liste des tâches ouvertes.
Pour plus d'informations, veuillez vous référer à la page Wiki et à la FAQ ?
⚠️ ce document fait référence à la version 2.X, vérifiez ici pour la version 3.X.
Les versions 2.X et 3.X de Swagger Codegen sont disponibles et sont entretenues indépendamment.
REMARQUES :
Les versions 2.X ( io.swagger ) et 3.X ( io.swagger.codegen.v3 ) ont des identifiants de groupe différents .
OpenAPI 3.0.X est pris en charge uniquement à partir de la version 3.X.
Pour des informations complètes sur la gestion des versions, veuillez vous référer à la documentation sur la gestion des versions.
Actuellement, les langages/frameworks suivants sont pris en charge :
Clients API : ActionScript , Ada , Apex , Bash , C# (.net 2.0, 3.5 ou version ultérieure), 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 for Java, Rassurez-vous), Kotlin , Lua , Node.js (ES5, ES6, AngularJS avec annotations du compilateur Google Closure) 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)
Stubs de serveur : 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)
Générateurs de documentation API : HTML , Confluence Wiki
Fichiers de configuration : Apache2
Autres : JMeter
Consultez OpenAPI-Spec pour plus d'informations sur le projet OpenAPI.
Gestion des versions
Compatibilité
Commencer
Générateurs
Pour générer un exemple de bibliothèque client
Générer des bibliothèques depuis votre serveur
Validation de votre spécification OpenAPI
Génération d'une documentation dynamique sur l'API HTML
Génération de la documentation statique de l'API HTML
Intégration du flux de travail
Générateurs en ligne
Contribution
Équipe principale de Swagger Codegen
La spécification OpenAPI a subi 3 révisions depuis sa création initiale en 2010. Les versions stables actuelles du projet Swagger Codegen ont les compatibilités suivantes avec la spécification OpenAPI :
| Version Swagger Codegen | Date de sortie | Compatibilité Swagger/OpenAPI Spec | Remarques |
|---|---|---|---|
| 3.0.62 ( actuellement stable ) | 2024-08-27 | 1.0, 1.1, 1.2, 2.0, 3.0 | balise v3.0.62 |
| 2.4.43 ( stable actuel ) | 2024-08-09 | 1.0, 1.1, 1.2, 2.0 | balise v2.4.42 |
Voici également un aperçu de ce qui s’en vient :
| Version Swagger Codegen | Date de sortie | Compatibilité Swagger/OpenAPI Spec | Remarques |
|---|---|---|---|
| 3.0.63-SNAPSHOT (actuel 3.0.0, prochaine version mineure) INSTANTANÉ | À déterminer | 1.0, 1.1, 1.2, 2.0, 3.0 | Version mineure |
| 2.4.44-SNAPSHOT (maître actuel, version mineure à venir) INSTANTANÉ | À déterminer | 1.0, 1.1, 1.2, 2.0 | Version mineure |
Pour une répartition détaillée de toutes les versions, veuillez consulter la liste complète de compatibilité.
Pour être opérationnel avec Swagger Codegen, consultez les guides et instructions suivants :
Conditions préalables
Bâtiment
Utiliser Docker
Une fois votre environnement configuré, vous êtes prêt à commencer à générer des clients et/ou des serveurs.
À titre d'exemple rapide, pour générer un client PHP pour https://petstore.swagger.io/v2/swagger.json, vous pouvez exécuter ce qui suit :
clone git https://github.com/swagger-api/swagger-codegencd swagger-codegen
paquet mvn propre
java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar générer
-je https://petstore.swagger.io/v2/swagger.json
-lphp
-o /var/tmp/php_api_clientRemarque : si vous êtes sous Windows, remplacez la dernière commande par
java -jar modulesswagger-codegen-clitargetswagger-codegen-cli.jar generate -i https://petstore.swagger.io/v2/swagger.json -l php -o c:tempphp_api_client
Vous pouvez également télécharger le JAR (dernière version) directement depuis maven.org
Pour obtenir une liste des options générales disponibles, vous pouvez exécuter la commande suivante :
java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar aide à générer
Pour obtenir une liste des options spécifiées par PHP (qui peuvent être transmises au générateur avec un fichier de configuration via l'option -c ), veuillez exécuter
java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar config-help -l php
Vous pouvez créer un client avec l'exemple d'API swagger petstore comme suit :
./bin/java-petstore.sh
(Sous Windows, exécutez plutôt .binwindowsjava-petstore.bat )
Cela exécutera le générateur avec cette commande :
java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar générer -je https://petstore.swagger.io/v2/swagger.json -ljava -o échantillons/client/animalerie/java
avec un certain nombre d'options. Vous pouvez obtenir les options avec la commande help generate (ci-dessous ne montre que des résultats partiels) :
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 Vous pouvez ensuite compiler et exécuter le client, ainsi que des tests unitaires sur celui-ci :
échantillons de cd/client/petstore/java paquet mvn
D'autres langues proposent également des échantillons en animalerie :
./bin/android-petstore.sh ./bin/java-petstore.sh ./bin/objc-petstore.sh
C'est tout aussi simple : utilisez simplement l'indicateur -i pour pointer vers un serveur ou un fichier.
? Swagger Codegen offre une tonne de flexibilité pour prendre en charge vos préférences de génération de code. Consultez la documentation des générateurs qui vous présente certaines des possibilités et montre comment générer à partir de fichiers locaux et ignorer les formats de fichiers.
Vous ne souhaiterez peut-être pas générer tous les modèles de votre projet. De même, vous souhaiterez peut-être qu’une ou deux API seulement soient écrites. Si tel est le cas, vérifiez les instructions de génération sélective.
Il existe différents aspects de la personnalisation du générateur de code au-delà de la simple création ou modification de modèles. Chaque langage dispose d'un fichier de configuration pris en charge pour gérer différents mappages de types ou apporter vos propres modèles. Pour plus d’informations, consultez la documentation de configuration avancée.
Vous avez des options. Le plus simple est d'utiliser notre validateur en ligne qui non seulement vous permettra de valider votre spécification, mais avec l'indicateur de débogage, vous pourrez voir ce qui ne va pas avec votre spécification. Par exemple, consultez Swagger Validator.
Si vous souhaitez avoir une validation directement sur votre propre machine, alors Spectral est une excellente option.
Pour ce faire, utilisez simplement l'indicateur -l dynamic-html lors de la lecture d'un fichier de spécifications. Cela crée une documentation HTML disponible sous forme d'application d'une seule page avec AJAX. Pour consulter la documentation :
échantillons de cd/dynamique-html/ installation npm nœud .
Ce qui lance un serveur node.js pour que les appels AJAX aient un endroit où aller.
Pour ce faire, utilisez simplement l'indicateur -l html lors de la lecture d'un fichier de spécifications. Cela crée un fichier HTML unique et simple avec du CSS intégré afin que vous puissiez l'envoyer sous forme de pièce jointe à un e-mail ou le charger à partir de votre système de fichiers :
échantillons de cd/html/ ouvrir index.html
Il est possible d'exploiter Swagger Codegen directement dans vos flux de travail CI/CD préférés pour rationaliser vos exigences de génération automatique. Consultez le guide d'intégration des workflows pour voir des informations sur nos options d'intégration Maven, Gradle et GitHub. ?
Si vous ne souhaitez pas exécuter et héberger votre propre instance de génération de code, consultez nos informations sur nos générateurs en ligne.
Veuillez vous référer à cette page
Les membres de l'équipe principale de Swagger Codegen sont des contributeurs qui ont apporté régulièrement des contributions significatives (révision des problèmes, correction de bugs, améliorations, etc.) au projet.
Les membres de l'équipe de base assument les responsabilités suivantes :
Fournit des conseils et des orientations aux autres utilisateurs
Examine les demandes d'extraction et les problèmes
Améliore le générateur en apportant des améliorations, en corrigeant des bugs ou en mettant à jour les documentations
Définit la direction technique du générateur
Veuillez divulguer tout problème ou vulnérabilité lié à la sécurité en envoyant un e-mail à [email protected], au lieu d'utiliser l'outil de suivi des problèmes public.
Le projet Swagger Codegen est destiné à être un avantage pour les utilisateurs de la spécification Swagger/Open API. Le projet lui-même possède la licence spécifiée. De plus, veuillez comprendre les points suivants :
Les modèles inclus avec ce projet sont soumis à la licence.
Le code généré n'est intentionnellement pas soumis à la licence du projet parent
Lorsque le code est généré à partir de ce projet, il doit être considéré TEL QUEL et appartenant à l'utilisateur du logiciel. Il n'y a aucune garantie, expresse ou implicite, pour le code généré. Vous pouvez en faire ce que vous voulez, et une fois généré, le code est sous votre responsabilité et soumis aux conditions de licence que vous jugez appropriées.
Nous aimerions remercier tous ceux qui ont contribué à Swagger Codegen, que ce soit en soulevant des problèmes, en corrigeant des bugs, en créant des modèles ou en créant du contenu utile dont d'autres pourront bénéficier.
