openapi json schema generator
4.5.1
Générez automatiquement un SDK client à partir de votre document OpenAPI 3.0.0-3.1.0 à l'aide du générateur de schéma OpenAPI JSON. Ce projet est un générateur de code qui se concentre sur la prise en charge de toutes les fonctionnalités OpenAPI et JSON.
Le générateur de schéma JSON OpenAPI permet une génération automatique des bibliothèques de clients API (génération SDK) étant donné un document OpenAPI (3.0.0-3.1.0 * sont pris en charge). Ce projet se concentre sur la création de la sortie 100% conforme aux spécifications de schéma OpenAPI + JSON. L'objectif est de soutenir pleinement tout ce qui est défini dans OpenAPI + les spécifications de schéma JSON incluses afin que les développeurs puissent utiliser toutes ces fonctionnalités.
Actuellement, les langues / cadres suivants sont pris en charge:
| Fonctionnalité | Python | Java | Kotlin |
|---|---|---|---|
| Statut de générateur | écurie | écurie | écurie |
| OpenAPI V3.0.0-3.1.0 ingestion | X | X | X |
| Support JSON Schema 2020-12 (composants / schémas) | X | X | X |
| Classes de schéma de composant + documentation produite | X | X | X |
| Documentation produite pour d'autres types de composants: En-têtes, paramètres, remaniements, rarespons, sécurité de sécurité | X | X | |
| Méthodes générées pour les points de terminaison qui envoient / reçoivent des documents JSON + générés pour eux | X | X |
from 1var , hi-there , etc.Nous utilisons un serveur Discord comme endroit pour poser des questions et nous aider mutuellement. Il offre des fonctionnalités très similaires à Slack. Vous pouvez nous rejoindre ici: https://discord.gg/mhb8wequyq
Oui; Les contributions sont les bienvenues! Soumettez un PR si vous souhaitez ajouter un nouvel échafaudage de serveur, un SDK client ou un générateur de documentation dans n'importe quelle langue.
La spécification OpenAPI a subi 3 révisions depuis la création initiale en 2010. Le projet OpenAPI-Json-Schema-Generator a les compatibilités suivantes avec la spécification OpenAPI:
| Version du générateur de schéma OpenAPI JSON | Compatibilité des spécifications OpenAPI |
|---|---|
| 3.3.0+ | 3.0.0 - 3.1.0 * |
| 3.1.0 - 3.2.1 | 3.0.0 - 3.1.0 |
| 1.0.0 - 3.0.0 | 3.0.0 - 3.0.3 |
OpenAPI V3.1.0 La prise en charge des spécifications comprend ces nouveaux mots clés de schéma JSON 2020-12:
Remarque: ces fonctionnalités peuvent également être vues dans les fonctionnalités du schéma de documentation du générateur
Pour construire à partir de Source, vous avez besoin des installations et disponibles suivantes dans votre $PATH:
Java 11
Apache Maven 3.9.3 ou plus
Après le clonage du projet, vous pouvez le construire à partir de la source avec cette commande:
mvn clean install La version par défaut contient une analyse statique minimale (via CheckStyle). Pour exécuter votre construction avec PMD et Spotbugs, utilisez le profil static-analysis :
mvn -Pstatic-analysis clean installL'image Docker agit comme un exécutable autonome. Il peut être utilisé comme alternative à l'installation via Homebrew, ou pour les développeurs qui ne sont pas en mesure d'installer Java ou de mettre à niveau la version installée.
Pour générer du code avec cette image, vous devrez monter un emplacement local en tant que volume.
Exemple:
docker run --rm -v " ${PWD} :/local " openapijsonschematools/openapi-json-schema-generator-cli generate
-i https://raw.githubusercontent.com/openapi-json-schema-tools/openapi-json-schema-generator/master/src/test/resources/3_0/petstore.yaml
-g python
-o /local/out/python Le code généré sera situé sous ./out/python dans le répertoire actuel.
Vous pouvez utiliser bin/run-in-docker.sh pour faire tout le développement. Ce script mappe votre référentiel local vers /gen dans le conteneur Docker. Il mappe également ~/.m2/repository à l'emplacement du conteneur approprié.
Pour exécuter mvn package :
git clone https://github.com/openapi-json-schema-tools/openapi-json-schema-generator
cd openapi-json-schema-generator
./bin/run-in-docker.sh mvn packageLes artefacts de construction sont désormais accessibles dans votre répertoire de travail.
Une fois construite, run-in-docker.sh servira d'Exécutable pour OpenAPi-Json-Schema-Generator-CLI. Pour générer du code, vous devrez sortir vers un répertoire sous /gen (par exemple /gen/out ). Par exemple:
./bin/run-in-docker.sh help # Executes 'help' command for openapi-json-schema-generator-cli
./bin/run-in-docker.sh list # Executes 'list' command for openapi-json-schema-generator-cli
./bin/run-in-docker.sh /gen/bin/python-petstore.sh # Builds the Python client
./bin/run-in-docker.sh generate -i src/test/resources/3_0/petstore.yaml
-g go -o /gen/out/python-petstore -p packageName=petstore_api # generates python client, outputs locally to ./out/python-petstore Si une erreur comme celle-ci se produit, exécutez simplement la commande MVN Clean Install -u :
org.apache.maven.lifecycle.lifecycleExecutionException: n'a pas réussi à exécuter le but org.apache.maven.plugins: maven-surefire-plagin: 2.19.1: test (test par défaut) sur le projet openapi-json-screma-generator: une incompatibilité de type s'est produite lors de l'exécution OpenAPI-json org.apache.maven.plugins: Maven-Surefire-Plugin: 2.19.1: Test: java.lang.ExceptioninInitializerror ne peut pas être jeté à java.io.ioexception
./run-in-docker.sh mvn clean install -UÉchec de l'exécution de but org.fortasoft: gradle-maven-plugin: 1.0.8: invoke (par défaut) sur le projet openapi-json-schema-generator-gradle-plugin-mvn-wrapper: org.gradle.tooling.buildException: n'a pas pu exécuter la construction en utilisant la distribution de gradle 'https://services.gradle.org/distributions/gradle-4.7-bin.zip'
En ce moment: aucune solution pour celle-ci: |
Pour générer un client Python pour petstore.yaml, veuillez exécuter ce qui suit
git clone https://github.com/openapi-json-schema-tools/openapi-json-schema-generator
cd openapi-json-schema-generator
mvn clean package
java -jar target/openapi-json-schema-generator-cli.jar generate
-i https://raw.githubusercontent.com/openapi-json-schema-tools/openapi-json-schema-generator/master/src/test/resources/3_0/petstore.yaml
-g python
-o /var/tmp/python_api_client (Si vous êtes sous Windows, remplacez la dernière commande par java -jar targetopenapi-json-schema-generator-cli.jar generate -i https://raw.githubusercontent.com/openapi-json-schema-tools/openapi-json-schema-generator/master/src/test/resources/3_0/petstore.yaml -g python -oc:temppython_api_client )
Pour obtenir une liste des options générales disponibles, veuillez exécuter java -jar target/openapi-json-schema-generator-cli.jar help generate
Pour obtenir une liste d'options spécifiées Python (qui peuvent être transmises au générateur avec un fichier de configuration via l'option -c ), veuillez exécuter java -jar target/openapi-json-schema-generator-cli.jar config-help -g python
Vous pouvez construire un client contre l'API Petstore comme suit:
./bin/generate-samples.sh ./bin/generate_samples_configs/python.yaml(Sur Windows, veuillez installer Git Bash pour Windows pour exécuter la commande ci-dessus)
Ce script exécutera le générateur avec cette commande:
java -jar target/openapi-json-schema-generator-cli.jar generate
-i https://raw.githubusercontent.com/openapijsonschematools/openapi-json-schema-generator/master/src/test/resources/3_0/petstore.yaml
-g python
-t src/main/resources/python
--additional-properties packageName=petstore_api
-o samples/client/petstore/pythonavec un certain nombre d'options. Les options Python sont documentées ici.
Vous pouvez également obtenir les options avec la commande help generate (ci-dessous affiche uniquement les résultats partiels):
NAME
openapi-json-schema-generator-cli generate - Generate code with the specified
generator.
SYNOPSIS
openapi-json-schema-generator-cli generate
[(-a <authorization> | --auth <authorization>)]
[--api-name-suffix <api name suffix>] [--api-package <api package>]
[--artifact-id <artifact id>] [--artifact-version <artifact version>]
[(-c <configuration file> | --config <configuration file>)] [--dry-run]
[(-e <templating engine> | --engine <templating engine>)]
[--enable-post-process-file]
[(-g <generator name> | --generator-name <generator name>)]
[--git-host <git host>] [--git-repo-id <git repo id>]
[--git-user-id <git user id>] [--global-property <global properties>...]
[--group-id <group id>] [--hide-generation-timestamp]
[--http-user-agent <http user agent>]
[(-i <spec file> | --input-spec <spec file>)]
[--ignore-file-override <ignore file override location>]
[--ints-allowed-for-float-double-formats]
[--invoker-package <invoker package>] [--minimal-update]
[--model-name-prefix <model name prefix>]
[--model-name-suffix <model name suffix>]
[(-o <output directory> | --output <output directory>)] [(-p <additional properties> | --additional-properties <additional properties>)...]
[--package-name <package name>] [--release-note <release note>]
[--remove-enum-value-prefix] [--remove-operation-id-prefix]
[(-s | --skip-overwrite)] [--skip-operation-example]
[--skip-validate-spec] [--strict-spec <true/false strict behavior>]
[(-t <template directory> | --template-dir <template directory>)]
[(-v | --verbose)]
OPTIONS
-a <authorization>, --auth <authorization>
adds authorization headers when fetching the OpenAPI definitions
remotely. Pass in a URL-encoded string of name:header with a comma
separating multiple values
--api-name-suffix <api name suffix>
Suffix that will be appended to all API names ('tags'). Default:
Api. e.g. Pet => PetApi. Note: Only ruby, python, jaxrs generators
support this feature at the moment.
--api-package <api package>
package for generated api classes
--artifact-id <artifact id>
artifactId in generated pom.xml. This also becomes part of the
generated library's filename
--artifact-version <artifact version>
artifact version in generated pom.xml. This also becomes part of the
generated library's filename
-c <configuration file>, --config <configuration file>
Path to configuration file. It can be JSON or YAML. If file is JSON,
the content should have the format {"optionKey":"optionValue",
"optionKey1":"optionValue1"...}. If file is YAML, the content should
have the format optionKey: optionValue. Supported options can be
different for each language. Run config-help -g {generator name}
command for language-specific config options.
--dry-run
Try things out and report on potential changes (without actually
making changes).
-e <templating engine>, --engine <templating engine>
templating engine: "handlebars"(default) or "mustache"
--enable-post-process-file
Enable post-processing file using environment variables.
-g <generator name>, --generator-name <generator name>
generator to use (see list command for list)
--git-host <git host>
Git host, e.g. gitlab.com.
--git-repo-id <git repo id>
Git repo ID, e.g. openapi-generator.
--git-user-id <git user id>
Git user ID, e.g. openapijsonschematools.
--global-property <global properties>
sets specified global properties (previously called 'system
properties') in the format of name=value,name=value (or multiple
options, each with name=value)
--group-id <group id>
groupId in generated pom.xml
--hide-generation-timestamp
Hides the generation timestamp when files are generated.
--http-user-agent <http user agent>
HTTP user agent, e.g. codegen_csharp_api_client, default to
'OpenAPI-Generator/{packageVersion}/{language}'
-i <spec file>, --input-spec <spec file>
location of the OpenAPI spec, as URL or file (required if not loaded
via config using -c)
--ignore-file-override <ignore file override location>
Specifies an override location for the .openapi-generator-ignore
file. Most useful on initial generation.
--ints-allowed-for-float-double-formats
Integers are allowed in for type: number format:float/double
payloads
--invoker-package <invoker package>
root package for generated code
--minimal-update
Only write output files that have changed.
--model-name-prefix <model name prefix>
Prefix that will be prepended to all model names.
--model-name-suffix <model name suffix>
Suffix that will be appended to all model names.
-o <output directory>, --output <output directory>
where to write the generated files (current dir by default)
-p <additional properties>, --additional-properties <additional
properties>
sets additional properties that can be referenced by the mustache
templates in the format of name=value,name=value. You can also have
multiple occurrences of this option.
--package-name <package name>
package for generated classes (where supported)
--release-note <release note>
Release note, default to 'Minor update'.
--remove-enum-value-prefix
Remove the common prefix of enum values
--remove-operation-id-prefix
Remove prefix of operationId, e.g. config_getId => getId
-s, --skip-overwrite
specifies if the existing files should be overwritten during the
generation.
--skip-operation-example
Skip examples defined in operations to avoid out of memory errors.
--skip-validate-spec
Skips the default behavior of validating an input specification.
--strict-spec <true/false strict behavior>
'MUST' and 'SHALL' wording in OpenAPI spec is strictly adhered to.
e.g. when false, no fixes will be applied to documents which pass
validation but don't follow the spec.
-t <template directory>, --template-dir <template directory>
folder containing the template files
-v, --verbose
verbose mode
Vous pouvez ensuite utiliser le client généré automatiquement. Le Readme.md est un bon point de départ.
D'autres générateurs ont également des échantillons.
Veuillez vous référer à Customation.md sur la façon de personnaliser la sortie (par exemple, nom du package, version)
Veuillez vous référer à Integration.md sur la façon d'intégrer le générateur OpenAPI avec Maven, Gradle, Github et CI / CD.
Le projet OpenAPI JSON Schema Generator est destiné à un avantage pour les utilisateurs de la spécification API Open. Le projet lui-même a la licence comme spécifié. De plus, veuillez comprendre les points suivants:
Lorsque le code est généré à partir de ce projet, il doit être pris en compte tel quel et détenu par l'utilisateur du logiciel. Il n'y a pas de garantie - exprimée ou implicite - du code généré. Vous pouvez faire ce que vous le souhaitez, et une fois généré, le code est votre responsabilité et soumis aux termes de licence que vous jugez appropriés.
Recherche de code github
Ce dépôt est basé sur V6.2.0 du générateur OpenAPI. Ce projet se concentre sur la création de la sortie 100% conforme au schéma JSON dans le cadre de la spécification OpenAPI 3.1 en mettant l'accent sur les cas complexes (approche de haut en bas). L'objectif est de soutenir pleinement tout ce qui est défini dans le schéma JSON afin que les développeurs puissent tirer parti du schéma JSON ainsi que des spécifications OpenAPI dans leur conception d'API. La construction ici permet des progrès plus rapides en soutenant les nouvelles fonctionnalités dans OpenAPI 3.x sans avoir à prendre en charge de nombreux générateurs plus anciens qui n'utilisent pas les nouvelles fonctionnalités.
Le générateur de schéma JSON OpenAPI est basé sur le générateur OpenAPI v6.2.0. Le projet a été créé ici parce que l'équipe OpenAPI-Generator Core a nécessité la suppression du générateur Python de son projet. L'auteur du générateur Python (@spacether) a préféré continuer à construire dans le référentiel OpenAPI-Generator, mais Core Team a refusé d'envisager de garder Python dans OpenAPI-Generator. Vous trouverez ci-dessous un calendrier de ces événements et certaines de leurs raisons:
Copyright 2023 OpenAPI-Json-Schema-Generator Contributeurs Copyright 2018 OpenAPI-Generator Contributeurs (https://openapi-generator.tech) Copyright 2018 SmartBear Software
Licencié sous la licence Apache, version 2.0 (la "licence"); Vous ne pouvez pas utiliser ce fichier sauf conforme à la licence. Vous pouvez obtenir une copie de la licence à apache.org/licenses/license-2.0
Sauf exiger la loi applicable ou convenu par écrit, les logiciels distribués en vertu de la licence sont distribués sur une base «tel quel», sans garantie ou conditions d'aucune sorte, expresse ou implicite. Voir la licence pour la langue spécifique régissant les autorisations et les limitations sous la licence.
