openapi json schema generator
4.5.1
Genere automáticamente un SDK de cliente desde su documento OpenAPI 3.0.0-3.1.0 utilizando el generador de esquema OpenApi JSON. Este proyecto es un generador de código que se centra en admitir todas las funciones de Schema OpenAPI y JSON.
El generador de esquema de OpenAPI JSON permite la generación automática de las bibliotecas de clientes API (generación SDK) dado un documento OpenAPI (3.0.0-3.1.0* son compatibles). Este proyecto se centra en hacer que la salida sea 100% que cumpla con las especificaciones de esquema OpenAPI + JSON. El objetivo es apoyar completamente todo lo que se define en OpenAPI + las especificaciones de esquema JSON incluidas para que los desarrolladores puedan usar todas esas características.
Actualmente, se admiten los siguientes idiomas/marcos:
| Característica | Pitón | Java | Kotlín |
|---|---|---|---|
| Estado del generador | estable | estable | estable |
| Openapi v3.0.0-3.1.0 Ingestión | incógnita | incógnita | incógnita |
| Soporte JSON Schema 2020-12 (componentes/esquemas) | incógnita | incógnita | incógnita |
| Clases de esquema de componentes + documentación producida | incógnita | incógnita | incógnita |
| Documentación producida para otros tipos de componentes: encabezados, parámetros, solicitudes de solicitudes, resonantes, SecuritySchemes | incógnita | incógnita | |
| Métodos generados para puntos finales que enviar/recibir JSON + documentos generados para ellos | incógnita | incógnita |
from 1var , hi-there , etc.Utilizamos un servidor de discordia como un lugar para hacer preguntas y ayudarnos mutuamente. Ofrece funcionalidad muy similar a Slack. Puedes unirte a nosotros aquí: https://discord.gg/MHB8Wequyq
Sí; ¡Las contribuciones son bienvenidas! Envíe un PR si desea agregar un nuevo andamio de servidor, SDK del cliente o generador de documentación en cualquier idioma.
La especificación de OpenAPI ha sufrido 3 revisiones desde la creación inicial en 2010. El proyecto OpenApi-JSON-SCHEMA-Generator tiene las siguientes compatibilidades con la especificación de OpenAPI:
| Versión del generador de esquema de Openapi JSON | Compatibilidad con especificaciones de 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 El soporte de especificaciones incluye estas palabras clave de esquema JSON nuevas/actualizadas:
Nota: Estas características también se pueden ver en las características del esquema de documentación del generador
Para construir desde la fuente, necesita lo siguiente instalado y disponible en su $PATH:
Java 11
Apache Maven 3.9.3 o más
Después de clonar el proyecto, puede construirlo desde la fuente con este comando:
mvn clean install La construcción predeterminada contiene un análisis estático mínimo (a través de checkstyle). Para ejecutar su compilación con PMD y Spotbugs, use el perfil static-analysis :
mvn -Pstatic-analysis clean installLa imagen de Docker actúa como un ejecutable independiente. Se puede utilizar como alternativa a la instalación a través de HomeBrew, o para desarrolladores que no pueden instalar Java o actualizar la versión instalada.
Para generar código con esta imagen, deberá montar una ubicación local como volumen.
Ejemplo:
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 El código generado se ubicará en ./out/python en el directorio actual.
Puede usar bin/run-in-docker.sh para hacer todo el desarrollo. Este script asigna su repositorio local a /gen en el contenedor Docker. También se mapea ~/.m2/repository a la ubicación del contenedor apropiado.
Para ejecutar 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 packageLos artefactos de construcción ahora se pueden acceder en su directorio de trabajo.
Una vez construido, run-in-docker.sh actuará como un ejecutable para Openapi-Json-Schema-Generator-Cli. Para generar código, deberá emitir un directorio en /gen ( /gen/out Ej. Por ejemplo:
./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 se produce un error como este, simplemente ejecute el comando MVN Clean Install -U :
org.apache.maven.lifecycle.lifecycleExecutionException: no pudo ejecutar meta org.apache.maven.plugins: maven-segurofire-plugin: 2.19.1: prueba (prueba predeterminada) en el proyecto openapi-json-schema-generator: un tipo de incompatibilidad ocurrió mientras se ejecuta ejecutando org.apache.maven.plugins: Maven-Surfire-Plugin: 2.19.1: Prueba: java.lang.ExceptionInitializerError no se puede lanzar a java.io.ioexception
./run-in-docker.sh mvn clean install -UNo se pudo ejecutar la meta org.fortasoft: Gradle-Maven-Plugin: 1.0.8: Invoke (predeterminado) en Project Openapi-Json-Schema-Generator-Gradle-Plugin-MVN-Wrapper: org.gradle.tooling.buildexception: no podría ejecutar la construcción utilizando la distribución de gradle 'https://services.gradle.org/distributions/gradle-4.7-bin.zip'
En este momento: no hay solución para este: |
Para generar un cliente de Python para petstore.yaml, ejecute lo siguiente
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 está en Windows, reemplace el último comando con 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 )
Para obtener una lista de opciones generales disponibles, ejecute java -jar target/openapi-json-schema-generator-cli.jar help generate
Para obtener una lista de opciones especificadas de Python (que se pueden pasar al generador con un archivo de configuración a través de la opción -c ), ejecute java -jar target/openapi-json-schema-generator-cli.jar config-help -g python
Puede construir un cliente contra la API de la tienda de mascotas de la siguiente manera:
./bin/generate-samples.sh ./bin/generate_samples_configs/python.yaml(En Windows, instale Git Bash para Windows para ejecutar el comando anterior)
Este script ejecutará el generador con este comando:
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/pythoncon varias opciones. Las opciones de Python están documentadas aquí.
También puede obtener las opciones con el comando help generate (a continuación solo muestra resultados parciales):
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
Luego puede usar el cliente generado automático. El ReadMe.md es un buen punto de partida.
Otros generadores también tienen muestras.
Consulte Customization.md sobre cómo personalizar la salida (por ejemplo, nombre del paquete, versión)
Consulte Integration.md sobre cómo integrar el generador OpenAPI con Maven, Gradle, GitHub y CI/CD.
El proyecto del generador de esquema OpenAPI JSON se pretende como un beneficio para los usuarios de la especificación de API Open. El proyecto en sí tiene la licencia como se especifica. Además, comprenda los siguientes puntos:
Cuando el código se genera a partir de este proyecto, se considerará tal como es y es propiedad del usuario del software. No hay garantías, expresadas o implícitas, código generado. Puede hacer lo que desee con él, y una vez generado, el código es su responsabilidad y sujeto a los términos de licencia que considera apropiados.
Búsqueda de código GitHub
Este repositorio se basa en V6.2.0 del generador OpenAPI. Este proyecto se centra en hacer que la salida sea 100% que cumpla con el esquema JSON como parte de la especificación OpenAPI 3.1 con un enfoque en casos complejos (enfoque de arriba hacia abajo). El objetivo es apoyar completamente todo lo que se define en el esquema JSON para que los desarrolladores puedan aprovechar el esquema JSON y la especificación de OpenAPI en su diseño API. La construcción aquí permite un progreso más rápido que admite nuevas características en OpenAPI 3.x sin tener que admitir muchos generadores anteriores que no utilizan las nuevas características.
OpenAPI JSON Schema Generator se basa en OpenAPI Generator V6.2.0. El proyecto se creó aquí porque el equipo central de Generator OpenApi requirió la eliminación del generador de Python de su proyecto. El autor del Generador de Python (@spacether) prefirió seguir construyendo en el repositorio de Generador Openapi, pero Core Team se negó a considerar mantener a Python en Openapi-Generator. A continuación se muestra una línea de tiempo de esos eventos y algunas de sus razones:
Copyright 2023 OpenApi-JSON-SCHEMA GENERATOR CONTRIGUADORES Copyright 2018 Openapi-Generator Colaboradores (https://openapi-generator.tech) Copyright 2018 SmartBear Software
Licenciado bajo la licencia Apache, versión 2.0 (la "licencia"); No puede usar este archivo, excepto de conformidad con la licencia. Puede obtener una copia de la licencia en apache.org/licenses/license-2.0
A menos que la ley aplicable sea requerida o acordado por escrito, el software distribuido bajo la licencia se distribuye de manera "como es", sin garantías o condiciones de ningún tipo, ya sea expresas o implícitas. Consulte la licencia para los permisos y limitaciones de rigor de idioma específico bajo la licencia.
