Auto generate a client sdk from your openapi 3.0.0-3.0.3 document using Openapi JSON Schema Generator.
This project is a code generator that focuses on supporting all openapi and json schema features.

Overview

OpenAPI JSON Schema Generator allows auto-generation of API client libraries (SDK generation) given an
OpenAPI Spec (3.0.0-3.0.3 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:

• python

Join Our Community

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

Reasons To Use the Python Generator

• Type hints on
• Run time type checking and validation checking when:
  • instantiating models
  • sending to endpoints
  • receiving from endpoints
  • Note: if needed, validation of json schema keywords can be deactivated via a SchemaConfiguration class
• mypy runs on sample petstore client and passes
  • passing mypy tests means that this generator could be ported into compiled languages lik java/kotlin/golang
• Autogenerated thorough testing of json schema keyword features in models and endpoints which come from the json schema test suite
• Tests are passing in CI
• Test endpoints are tagged by the relevant keyword like type/format/allOf 25+ keywords and counting
• Code re-use built in from the ground up
  • components/schemas/headers etc are generated as separate classes and imported when used via $ref
• Openapi spec inline schemas supported at any depth in any location
• Format support for: int32, int64, float, double, binary, date, datetime, uuid
• Invalid (in python) property names supported like from, 1var, hi-there etc in
  • schema property names
  • endpoint parameter names
• Payload values are not coerced when validated, so a datetime value can pass other validations that describe the payload only as type string
• types are generated for enums of type string/integer/boolean using typing.Literal
• String transmission of numbers supported with type: string, format: number, value can be accessed as a Decimal with schemas.as_decimal(inst)
• Multiple content types supported for request and response bodies
• Endpoint response always also includes the urllib3.HTTPResponse
• Endpoint response deserialization can be skipped with the skip_deserialization argument

And many more!

• Docs for the python generator
• generated client sample code
  • Openapi v3.0.3 general petstore spec, general features
• generated client sample code
  • Openapi json schema v3.0.3 unit test spec

Can I build here?

Yes; contributions are welcome!
Submit a PR if you want to add a new server scaffold, client sdk, or documentation generator in any language.

Table of contents

• OpenAPI JSON Schema Generator
• Overview
• Table of Contents
• Installation
  • Compatibility
  • Build Projects
  • Docker
• Getting Started
• Usage
  • Customization
  • Workflow Integration
  • License Information
• Companies/Projects using OpenAPI JSON Schema Generator
• About Us
  • History of OpenAPI JSON Schema Generator
• License

Installation

Compatibility

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:

Build Projects

To build from source, you need the following installed and available in your $PATH:

• Java 11

• Apache Maven 3.9.3 or greater

After cloning the project, you can build it from source with this command:

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

Docker

Public Pre-built Docker images

• https://hub.docker.com/r/openapijsonschematools/openapi-json-schema-generator-cli/ (official CLI)

OpenAPI JSON Schema Generator CLI Docker Image

The OpenAPI JSON Schema Generator 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.

Development in docker

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 Go 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

Troubleshooting

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 :|

Getting Started

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 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 -o c:temppython_api_client)

You can also download the JAR (latest release) directly from maven.org

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 PHP 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 php

Usage

To generate a sample client library

You can build a client against the Petstore API as follows:

./bin/generate-samples.sh ./bin/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):

Tags: OpenAPISchema

0Likes

Written by

HackTech

View all posts by HackTech