Auto generate a client sdk from your openapi 3.0.0-3.1.0 document using Openapi JSON Schema Generator. This project is a code generator that focuses on supporting all openapi and json schema features.
OpenAPI JSON Schema Generator allows auto-generation of API client libraries (SDK generation) given an OpenAPI document (3.0.0-3.1.0* are supported). This project focuses on making the output 100% compliant with openapi + JSON schema specs. The goal is to fully support everything defined in openapi + the included JSON schema specs so developers can use all of those features.
Currently, the following languages/frameworks are supported:
Feature | Python | Java | Kotlin |
---|---|---|---|
Generator status | stable | stable | stable |
Openapi v3.0.0-3.1.0 ingestion | X | X | X |
Json Schema 2020-12 Support (components/schemas) | X | X | X |
Component schema classes + documentation produced | X | X | X |
Documentation produced for other component types: headers, parameters, requestBodies, ressponses, securitySchemes |
X | X | |
Methods generated for endpoints that send/receive json + docs generated for them |
X | X |
from
, 1var
, hi-there
etc in
We use a Discord server as a place to ask questions and help each other. It offers functionality very similar to Slack. You can join us here: https://discord.gg/mHB8WEQuYQ
Yes; contributions are welcome! Submit a PR if you want to add a new server scaffold, client sdk, or documentation generator in any language.
The OpenAPI Specification has undergone 3 revisions since initial creation in 2010. The openapi-json-schema-generator project has the following compatibilities with the OpenAPI Specification:
OpenAPI JSON Schema Generator Version | OpenAPI Spec compatibility |
---|---|
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 specification support includes these new/updated 2020-12 json schema keywords:
Note: these features can also be seen in the generator documentation schema features
To build from source, you need the following installed and available in your $PATH:
After cloning the project, you can build it from source with this command:
mvn clean install
The default build contains minimal static analysis (via CheckStyle). To run your build with PMD and Spotbugs, use the static-analysis
profile:
mvn -Pstatic-analysis clean install
The docker image acts as a standalone executable. It can be used as an alternative to installing via homebrew, or for developers who are unable to install Java or upgrade the installed version.
To generate code with this image, you'll need to mount a local location as a volume.
Example:
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
The generated code will be located under ./out/python
in the current directory.
You can use bin/run-in-docker.sh
to do all development. This script maps your local repository to /gen
in the docker container. It also maps ~/.m2/repository
to the appropriate container location.
To execute 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
Build artifacts are now accessible in your working directory.
Once built, run-in-docker.sh
will act as an executable for openapi-json-schema-generator-cli. To generate code, you'll need to output to a directory under /gen
(e.g. /gen/out
). For example:
./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
If an error like this occurs, just execute the mvn clean install -U command:
org.apache.maven.lifecycle.LifecycleExecutionException: Failed to execute goal org.apache.maven.plugins:maven-surefire-plugin:2.19.1:test (default-test) on project openapi-json-schema-generator: A type incompatibility occurred while executing org.apache.maven.plugins:maven-surefire-plugin:2.19.1:test: java.lang.ExceptionInInitializerError cannot be cast to java.io.IOException
./run-in-docker.sh mvn clean install -U
Failed to execute goal org.fortasoft:gradle-maven-plugin:1.0.8:invoke (default) on project openapi-json-schema-generator-gradle-plugin-mvn-wrapper: org.gradle.tooling.BuildException: Could not execute build using Gradle distribution 'https://services.gradle.org/distributions/gradle-4.7-bin.zip'
Right now: no solution for this one :|
To generate a python client for petstore.yaml, please run the following
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 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 c:\temp\python_api_client
)
To get a list of general options available, please run java -jar target/openapi-json-schema-generator-cli.jar help generate
To get a list of python specified options (which can be passed to the generator with a config file via the -c
option), please run java -jar target/openapi-json-schema-generator-cli.jar config-help -g python
You can build a client against the Petstore API as follows:
./bin/generate-samples.sh ./bin/generate_samples_configs/python.yaml
(On Windows, please install GIT Bash for Windows to run the command above)
This script will run the generator with this command:
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
with a number of options. The python options are documented here.
You can also get the options with the help generate
command (below only shows partial results):
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)]
You can then use the auto-generated client. The README.md is a good starting point.
Other generators have samples too.
Please refer to customization.md on how to customize the output (e.g. package name, version)
Please refer to integration.md on how to integrate OpenAPI generator with Maven, Gradle, Github and CI/CD.
The OpenAPI JSON Schema Generator project is intended as a benefit for users of the Open API Specification. The project itself has the License as specified. In addition, please understand the following points:
When code is generated from this project, it shall be considered AS IS and owned by the user of the software. There are no warranties--expressed or implied--for generated code. You can do what you wish with it, and once generated, the code is your responsibility and subject to the licensing terms that you deem appropriate.
This repo is based on v6.2.0 of OpenAPI Generator. This project focuses on making the output 100% compliant with JSON schema as part of the OpenAPI 3.1 specification with a focus on complex cases (top-down approach). The goal is to fully support everything defined in JSON schema so that developers can leverage JSON schema as well as OpenAPI specification in their API design. Building here allows for more rapid progress supporting new features in OpenAPI 3.X without having to support many older generators which don't use the new features.
OpenAPI JSON Schema Generator is based on OpenAPI Generator v6.2.0. The project was created here because the openapi-generator core team required the removal of the python generator from their project. The author of the python generator (@spacether) preferred to keep building in the openapi-generator repo, but core team refused to consider keeping python in openapi-generator. Below is a timeline of those events and some of their reasons:
Copyright 2023 OpenAPI-Json-Schema-Generator Contributors Copyright 2018 OpenAPI-Generator Contributors (https://openapi-generator.tech) Copyright 2018 SmartBear Software
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.