openapi json schema generator
4.5.1
Автоматическое генерируйте клиент SDK из вашего документа OpenAPI 3.0.0-3.1.0 с использованием генератора схемы OpenApi JSON. Этот проект является генератором кода, который фокусируется на поддержке всех функций схемы OpenAPI и JSON.
Generator Generator схемы схемы Openapi JSON позволяет автоматически генерировать клиентских библиотек API (Generation SDK) с учетом документа OpenAPI (3.0.0-3.1.0* поддерживается). Этот проект фокусируется на том, чтобы сделать выход на 100% совместимой со спецификациями схемы OpenAPI + JSON. Цель состоит в том, чтобы полностью поддерживать все, что определено в OpenAPI + включенные спецификации схемы JSON, чтобы разработчики могли использовать все эти функции.
В настоящее время поддерживаются следующие языки/фреймворки:
| Особенность | Питон | Ява | Котлин |
|---|---|---|---|
| Статус генератора | стабильный | стабильный | стабильный |
| Openapi v3.0.0-3.1.0 Приглашение | Х | Х | Х |
| Поддержка JSON Schema 2020-12 (компоненты/схемы) | Х | Х | Х |
| Компонентные схемы классов + документация | Х | Х | Х |
| Документация, созданная для других типов компонентов: Заголовки, параметры, requestbodies, ressponses, securityschemes | Х | Х | |
| Методы, генерируемые для конечных точек которые отправляют/получают JSON + DOCS, сгенерированные для них | Х | Х |
from , 1var , hi-there и т. Д.Мы используем сервер Discord в качестве места, чтобы задавать вопросы и помогать друг другу. Он предлагает функциональность, очень похожие на Slack. Вы можете присоединиться к нам здесь: https://discord.gg/mhb8wequyq
Да; Взносы приветствуются! Отправьте PR, если вы хотите добавить новый серверный каркас, клиент SDK или генератор документации на любом языке.
Спецификация OpenAPI претерпела 3 пересмотра с момента начального создания в 2010 году. Проект OpenAPI-JSON-Schema-Generator имеет следующие совместимости со спецификацией OpenAPI:
| Openapi json generator version | 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 |
Поддержка спецификации OpenApi v3.1.0 включает в себя эти новые/обновленные ключевые слова схемой схемы 2020-12 гг.
Примечание. Эти функции также можно увидеть в функциях схемы документации генератора
Чтобы построить из источника, вам нужно следующее установлено и доступно в вашем $PATH:
Java 11
Apache Maven 3.9.3 или более
После клонирования проекта вы можете построить его из источника с этой командой:
mvn clean install Сборка по умолчанию содержит минимальный статический анализ (через Checkstyle). Чтобы запустить свою сборку с помощью PMD и SpotBugs, используйте профиль static-analysis :
mvn -Pstatic-analysis clean installИзображение Docker действует как автономный исполняемый файл. Его можно использовать в качестве альтернативы установке через Homebrew или для разработчиков, которые не могут установить Java или обновить установленную версию.
Чтобы сгенерировать код с помощью этого изображения, вам нужно установить локальное место в качестве тома.
Пример:
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 Сгенерированный код будет расположен под ./out/python в текущем каталоге.
Вы можете использовать bin/run-in-docker.sh чтобы сделать всю разработку. Этот скрипт отображает ваш локальный репозиторий в /gen в контейнере Docker. Это также отображает ~/.m2/repository в соответствующее местоположение контейнера.
Чтобы выполнить 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 packageСтроительные артефакты теперь доступны в вашем рабочем каталоге.
После построения, run-in-docker.sh будет выступать в качестве исполняемого файла для openapi-json-schema-generator-cli. Чтобы сгенерировать код, вам нужно вывести в каталог в соответствии с /gen (например /gen/out ). Например:
./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 Если возникает такая ошибка, просто выполните команду MVN Clean Install -u :
org.apache.maven.lifecycle.lifecycleexecutionexception: не удалось выполнить цель org.apache.maven.plugins: maven-surefire-plugin: 2.19.1: тест (тест по умолчанию) на проекте openapi-json-schema-генератор: неспособность типа произошел при выполнении. org.apache.maven.plugins: maven-surefire-plugin: 2.19.1: тест: java.lang.exceptionInitializererror не может быть поднят на java.io.ioexception
./run-in-docker.sh mvn clean install -UНе удалось выполнить цель org.fortasoft: gradle-maven-plugin: 1.0.8: invoke (по умолчанию) на проекте openapi-json-schema-generator-gradle-plugin-mvn-wrapper: org.gradle.tooling.buildexcept 'https://services.gradle.org/distribitions/gradle-4.7bin.zip'
Прямо сейчас: нет решения для этого: |
Чтобы сгенерировать клиент Python для Petstore.yaml, пожалуйста, запустите следующее
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 (Если вы находитесь в Windows, замените последнюю команду на 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 )
Чтобы получить список общих вариантов, пожалуйста, запустите java -jar target/openapi-json-schema-generator-cli.jar help generate
Чтобы получить список указанных параметров Python (которые можно передавать в генератор с помощью файла конфигурации через опцию -c ), пожалуйста, запустите java -jar target/openapi-json-schema-generator-cli.jar config-help -g python
Вы можете построить клиента против Petstore API следующим образом:
./bin/generate-samples.sh ./bin/generate_samples_configs/python.yaml(В Windows, пожалуйста, установите Git Bash для Windows, чтобы запустить команду выше)
Этот сценарий запустит генератор с этой командой:
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/pythonс рядом вариантов. Параметры Python задокументированы здесь.
Вы также можете получить параметры с помощью команды help generate (ниже показывает только частичные результаты):
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
Затем вы можете использовать клиент с автоматическим сгенерированным. Readme.md - хорошая отправная точка.
У других генераторов тоже есть образцы.
Пожалуйста, обратитесь к настройке.md о том, как настроить выход (например, имя пакета, версия)
Пожалуйста, обратитесь к Integration.md о том, как интегрировать генератор OpenAPI с Maven, Gradle, Github и CI/CD.
Проект Generator Generator Generator OpenAPI JSON предназначен как преимущество для пользователей спецификации API Open. Сам проект имеет лицензию, как указано. Кроме того, пожалуйста, поймите следующие моменты:
Когда код генерируется из этого проекта, он должен рассматриваться как есть и принадлежит пользователю программного обеспечения. Нет никаких гарантий-экспрессированных или подразумеваемых-для сгенерированного кода. Вы можете делать то, что вы пожелаете с ним, и после создания код является вашей ответственностью и подчиняется условиям лицензирования, которые вы считаете целесообразными.
Поиск кода GitHub
Это репо основано на V6.2.0 генератора OpenAPI. Этот проект фокусируется на том, что вывод на 100% соответствует схеме JSON в рамках спецификации OpenAPI 3.1 с акцентом на сложные случаи (сверху вниз) подход). Цель состоит в том, чтобы полностью поддерживать все, что определено в схеме JSON, чтобы разработчики могли использовать схему JSON, а также спецификацию OpenAPI в их дизайне API. Строительство здесь обеспечивает более быстрый прогресс, поддерживая новые функции в OpenAPI 3.x без необходимости поддерживать многие старые генераторы, которые не используют новые функции.
Generator Generator схемы схемы Openapi JSON основан на генераторе OpenAPI V6.2.0. Проект был создан здесь, потому что основной команде Goor-Genator OpenAPI потребовалось удаление генератора Python из их проекта. Автор генератора Python (@spacether) предпочел продолжать строить в репо openapi-генераторе, но Core Team отказалась рассмотреть вопрос о сохранении Python в GoNAPI-генераторе. Ниже приведен график этих событий и некоторые из их причин:
Copyright 2023 Openapi-json-schema-генераторы авторов Copyright 2018 Apperapi Generator Apportors (https://openapi-generator.tech) Copyright 2018 SmartBear Software
Лицензировано по лицензии Apache, версия 2.0 («Лицензия»); Вы не можете использовать этот файл, кроме как в соответствии с лицензией. Вы можете получить копию лицензии по адресу apache.org/licenses/license-2.0
Если не требуется применимый закон или не согласен в письменной форме, программное обеспечение, распространяемое по лицензии, распределяется по основам «как есть», без каких -либо гарантий или условий, явных или подразумеваемых. См. Лицензию для конкретного языка, регулирующих разрешения и ограничения по лицензии.
