openapi json schema generator
4.5.1
Gerar automaticamente um SDK do cliente no seu documento OpenAPI 3.0.0-3.1.0 usando o OpenAPI JSON Schema Gerator. Este projeto é um gerador de código que se concentra no suporte a todos os recursos do Schema OpenAPI e JSON.
O OpenAPI JSON Schema Generator permite a geração automática de bibliotecas de clientes da API (geração SDK), dado um documento OpenAPI (3.0.0-3.1.0* são suportados). Este projeto se concentra em tornar a saída 100% compatível com as especificações do esquema OpenAPI + JSON. O objetivo é suportar completamente tudo o que é definido no OpenAPI + as especificações do esquema JSON incluído para que os desenvolvedores possam usar todos esses recursos.
Atualmente, os seguintes idiomas/estruturas são suportados:
| Recurso | Python | Java | Kotlin |
|---|---|---|---|
| Status do gerador | estável | estável | estável |
| Openapi v3.0.0-3.1.0 Ingestão | X | X | X |
| JSON Schema 2020-12 Suporte (componentes/esquemas) | X | X | X |
| Classes de esquema de componentes + documentação produzida | X | X | X |
| Documentação produzida para outros tipos de componentes: Cabeçalhos, parâmetros, códigos de solicitação, Ressponses, SecuritySchemes | X | X | |
| Métodos gerados para pontos de extremidade que enviam/recebem JSON + DOCs gerados para eles | X | X |
from , 1var , hi-there etc.Usamos um servidor Discord como um local para fazer perguntas e ajudar um ao outro. Oferece funcionalidade muito semelhante ao Slack. Você pode se juntar a nós aqui: https://discord.gg/mhb8wequyq
Sim; As contribuições são bem -vindas! Envie um PR se desejar adicionar um novo andaime de servidor, SDK do cliente ou gerador de documentação em qualquer idioma.
A especificação OpenAPI passou por 3 revisões desde a criação inicial em 2010. O projeto OpenApi-JSON-Schema-Generator tem as seguintes compatibilidades com a especificação OpenAPI:
| Versão do Gerador de Esquema JSON JSON OpenApi | Compatibilidade do OpenApi Spec |
|---|---|
| 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 |
O suporte à especificação do OpenAPI v3.1.0 inclui essas palavras-chave do Schema JSON de 2020-12 novas/atualizadas:
Nota: Esses recursos também podem ser vistos nos recursos do esquema de documentação do gerador
Para construir a partir da fonte, você precisa do seguinte instalado e disponível no seu $PATH:
Java 11
Apache Maven 3.9.3 ou maior
Depois de clonar o projeto, você pode construí -lo a partir da fonte com este comando:
mvn clean install A compilação padrão contém análise estática mínima (via estilo de seleção). Para executar sua construção com PMD e Spotbugs, use o perfil static-analysis :
mvn -Pstatic-analysis clean installA imagem do Docker atua como um executável independente. Ele pode ser usado como uma alternativa à instalação via Homebrew ou para desenvolvedores que não conseguem instalar o Java ou atualizar a versão instalada.
Para gerar código com esta imagem, você precisará montar um local local como volume.
Exemplo:
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 O código gerado estará localizado em ./out/python no diretório atual.
Você pode usar bin/run-in-docker.sh para fazer todo o desenvolvimento. Este script mapeia o repositório local para /gen no recipiente do docker. Ele também mapeia ~/.m2/repository para a localização apropriada do contêiner.
Para executar 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 packageOs artefatos de construção agora estão acessíveis em seu diretório de trabalho.
Uma vez construído, run-in-docker.sh atuará como um executável para o OpenApi-JSON-Schema-Generator-Cli. Para gerar código, você precisará produzir para um diretório em /gen (por exemplo, /gen/out ). Por exemplo:
./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 Se ocorrer um erro como esse, basta executar o comando de instalação limpo do MVN :
org.apache.maven.lifecycle.lifecyclexecutionException: falhou ao executar o objetivo org.apache.maven.plugins: maven-surefire-plugin: 2.19.1: teste (teste padrão) no projeto OpenApi-json-schema-generator: um tipo incompatibilidade Ocorre org.apache.maven.plugins: maven-surefire-plugin: 2.19.1: teste: java.lang.ExceptioninInitializerError não pode ser lançado para java.io.ioException
./run-in-docker.sh mvn clean install -UFalha ao executar a meta org.formasoft: gradle-maven-plugin: 1.0.8: Invoke (padrão) no projeto OpenApi-json-schema-generator-gradle-plugin-mvn-wrapper: org.gradle.tooling.buildException: não conseguiu a construção de graduação em distribuição gradle 'https://services.gradle.org/distributions/gradle-4.7-bin.zip'
Agora: nenhuma solução para este: |
Para gerar um cliente Python para petstore.yaml, execute o seguinte
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 (if you're on Windows, replace the last command with 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 obter uma lista de opções gerais disponíveis, execute java -jar target/openapi-json-schema-generator-cli.jar help generate
Para obter uma lista de opções especificadas do Python (que podem ser passadas para o gerador com um arquivo de configuração por meio da opção -c ), execute java -jar target/openapi-json-schema-generator-cli.jar config-help -g python
Você pode construir um cliente contra a API da PetStore da seguinte maneira:
./bin/generate-samples.sh ./bin/generate_samples_configs/python.yaml(No Windows, instale o Git Bash para o Windows para executar o comando acima)
Este script executará o gerador com 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/pythoncom várias opções. As opções do Python estão documentadas aqui.
Você também pode obter as opções com o comando help generate (abaixo mostra apenas resultados parciais):
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
Você pode usar o cliente gerado automaticamente. O readme.md é um bom ponto de partida.
Outros geradores também têm amostras.
Consulte a personalização.md sobre como personalizar a saída (por exemplo, nome do pacote, versão)
Consulte a integração.md sobre como integrar o generador OpenAPI com maven, gradle, github e ci/cd.
O Projeto Gerador de Esquema JSON JSON JSON destina -se como um benefício para os usuários da especificação da API aberta. O projeto em si tem a licença conforme especificado. Além disso, entenda os seguintes pontos:
Quando o código for gerado a partir deste projeto, ele deve ser considerado como está e de propriedade do usuário do software. Não há garantias-expressas ou implícitas-para o código gerado. Você pode fazer o que deseja e, uma vez gerado, o código é de sua responsabilidade e sujeito aos termos de licenciamento que você considera apropriado.
Pesquisa de código do Github
Este repositório é baseado no v6.2.0 do gerador OpenAPI. Este projeto se concentra em tornar a saída 100% compatível com o JSON Schema como parte da especificação OpenAPI 3.1, com foco em casos complexos (abordagem de cima para baixo). O objetivo é suportar totalmente tudo o que é definido no JSON Schema para que os desenvolvedores possam aproveitar o esquema JSON, bem como a especificação do OpenAPI em seu design de API. A construção aqui permite um progresso mais rápido que suporta novos recursos no OpenAPI 3.x sem precisar suportar muitos geradores mais velhos que não usam os novos recursos.
O generador de esquema JSON OpenAPI é baseado no gerador OpenAPI v6.2.0. O projeto foi criado aqui porque a equipe central do OpenApi-Generator exigia a remoção do gerador Python de seu projeto. O autor do gerador Python (@spacether) preferia continuar construindo no repositório do OpenAPI-Generator, mas a equipe principal se recusou a considerar manter o Python no OpenApi-Generator. Abaixo está uma linha do tempo desses eventos e algumas de suas razões:
Copyright 2023 Openapi-JSON-Schema-Generator Colaboradores Copyright 2018 Contribuintes OpenApi-Generator (https://openapi-generator.tech) Copyright 2018 SmartBear Software
Licenciado sob a licença Apache, versão 2.0 (a "licença"); Você não pode usar esse arquivo, exceto em conformidade com a licença. Você pode obter uma cópia da licença em apache.org/license/license-2.0
A menos que exigido pela lei aplicável ou acordada por escrito, o software distribuído pela licença é distribuído "como está", sem garantias ou condições de qualquer tipo, expressa ou implícita. Consulte a licença para o idioma específico que rege as permissões e limitações sob a licença.
