2qxx/openapi-generator repository overview

⁠OpenAPI Generator

⁠Sponsors

If you find OpenAPI Generator useful for work, please consider asking your company to support this Open Source project by becoming a sponsor⁠. You can also individually sponsor the project by becoming a backer⁠.

⁠Thank you to our bronze sponsors!

⁠Thank you GoDaddy for sponsoring the domain names, Linode for sponsoring the VPS and Checkly for sponsoring the API monitoring

⁠Overview

OpenAPI Generator allows generation of API client libraries (SDK generation), server stubs, documentation and configuration automatically given an OpenAPI Spec⁠ (both 2.0 and 3.0 are supported). Currently, the following languages/frameworks are supported:

⁠Table of contents

• OpenAPI Generator⁠
• Overview⁠
• Table of Contents⁠
• 1 - Installation⁠
  • 1.1 - Compatibility⁠
  • 1.2 - Artifacts on Maven Central⁠
  • 1.3 - Download JAR⁠
  • 1.4 - Build Projects⁠
  • 1.5 - Homebrew⁠
  • 1.6 - Docker⁠
  • 1.7 - NPM⁠
• 2 - Getting Started⁠
• 3 - Usage⁠
  • 3.1 - Customization⁠
  • 3.2 - Workflow Integration⁠
  • 3.3 - Online Generators⁠
  • 3.4 - License Information on Generated Code⁠
  • 3.5 - IDE Integration⁠
• 4 - Companies/Projects using OpenAPI Generator⁠
• 5 - Presentations/Videos/Tutorials/Books⁠
• 6 - About Us⁠
  • 6.1 - OpenAPI Generator Core Team⁠
  • 6.2 - OpenAPI Generator Technical Committee⁠
  • 6.3 - History of OpenAPI Generator⁠
• 7 - License⁠

⁠1 - Installation⁠

⁠1.1 - Compatibility⁠

The OpenAPI Specification has undergone 3 revisions since initial creation in 2010. The openapi-generator project has the following compatibilities with the OpenAPI Specification:

OpenAPI Spec compatibility: 1.0, 1.1, 1.2, 2.0, 3.0

For old releases, please refer to the Release⁠ page.

⁠1.2 - Artifacts on Maven Central⁠

You can find our released artifacts on maven central:

Core:

<dependency>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator</artifactId>
    <version>${openapi-generator-version}</version>
</dependency>

See the different versions of the openapi-generator⁠ artifact available on maven central.

Cli:

<dependency>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-cli</artifactId>
    <version>${openapi-generator-version}</version>
</dependency>

See the different versions of the openapi-generator-cli⁠ artifact available on maven central.

Maven plugin:

<dependency>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>${openapi-generator-version}</version>
</dependency>

• See the different versions of the openapi-generator-maven-plugin⁠ artifact available on maven central.
• Readme⁠

Gradle plugin:

<dependency>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-gradle-plugin</artifactId>
    <version>${openapi-generator-version}</version>
</dependency>

• See the different versions of the openapi-generator-gradle-plugin⁠ artifact available on maven central.
• Readme⁠

⁠1.3 - Download JAR⁠

If you're looking for the latest stable version, you can grab it directly from Maven.org (Java 8 runtime at a minimum):

JAR location: https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/5.0.0-beta/openapi-generator-cli-5.0.0-beta.jar

For Mac/Linux users:

wget https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/5.0.0-beta/openapi-generator-cli-5.0.0-beta.jar -O openapi-generator-cli.jar

For Windows users, you will need to install wget⁠ or you can use Invoke-WebRequest in PowerShell (3.0+), e.g.

Invoke-WebRequest -OutFile openapi-generator-cli.jar https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/5.0.0-beta/openapi-generator-cli-5.0.0-beta.jar

After downloading the JAR, run java -jar openapi-generator-cli.jar help to show the usage.

For Mac users, please make sure Java 8 is installed (Tips: run java -version to check the version), and export JAVA_HOME in order to use the supported Java version:

export JAVA_HOME=`/usr/libexec/java_home -v 1.8`
export PATH=${JAVA_HOME}/bin:$PATH

⁠Launcher Script

One downside to manual jar downloads is that you don't keep up-to-date with the latest released version. We have a Bash launcher script at bin/utils/openapi-generator.cli.sh⁠ which resolves this issue.

To install the launcher script, copy the contents of the script to a location on your path and make the script executable.

An example of setting this up (NOTE: Always evaluate scripts curled from external systems before executing them).

mkdir -p ~/bin/openapitools
curl https://raw.githubusercontent.com/OpenAPITools/openapi-generator/master/bin/utils/openapi-generator-cli.sh > ~/bin/openapitools/openapi-generator-cli
chmod u+x ~/bin/openapitools/openapi-generator-cli
export PATH=$PATH:~/bin/openapitools/

Now, openapi-generator-cli is "installed". On invocation, it will query the GitHub repository for the most recently released version. If this matches the last downloaded jar, it will execute as normal. If a newer version is found, the script will download the latest release and execute it.

If you need to invoke an older version of the generator, you can define the variable OPENAPI_GENERATOR_VERSION either ad hoc or globally. You can export this variable if you'd like to persist a specific release version.

Examples:

# Execute latest released openapi-generator-cli
openapi-generator-cli version

# Execute version 3.1.0 for the current invocation, regardless of the latest released version
OPENAPI_GENERATOR_VERSION=3.1.0 openapi-generator-cli version

# Execute version 3.1.0-SNAPSHOT for the current invocation
OPENAPI_GENERATOR_VERSION=3.1.0-SNAPSHOT openapi-generator-cli version

# Execute version 3.0.2 for every invocation in the current shell session
export OPENAPI_GENERATOR_VERSION=3.0.2
openapi-generator-cli version # is 3.0.2
openapi-generator-cli version # is also 3.0.2

# To "install" a specific version, set the variable in .bashrc/.bash_profile
echo "export OPENAPI_GENERATOR_VERSION=3.0.2" >> ~/.bashrc
source ~/.bashrc
openapi-generator-cli version # is always 3.0.2, unless any of the above overrides are done ad hoc

⁠1.4 - Build Projects⁠

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

• Java 8⁠

• Apache Maven 3.3.4 or greater⁠

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

mvn clean install

If you don't have maven installed, you may directly use the included maven wrapper⁠, and build with the command:

./mvnw 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

⁠1.5 - Homebrew⁠

To install, run brew install openapi-generator

Here is an example usage to generate a Ruby client:

openapi-generator generate -i https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml -g ruby -o /tmp/test/

To reinstall with the latest master, run brew uninstall openapi-generator && brew install --HEAD openapi-generator

To install OpenJDK (pre-requisites), please run

brew tap AdoptOpenJDK/openjdk
brew cask install adoptopenjdk12
export JAVA_HOME=/Library/Java/JavaVirtualMachines/jdk-12.0.2.jdk/Contents/Home/

To install Maven, please run

brew install maven

⁠1.6 - Docker⁠

⁠Public Pre-built Docker images

• https://hub.docker.com/r/openapitools/openapi-generator-cli/⁠ (official CLI)
• https://hub.docker.com/r/openapitools/openapi-generator-online/⁠ (official web service)

⁠OpenAPI Generator CLI Docker Image

The OpenAPI 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" openapitools/openapi-generator-cli generate \
    -i https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/2_0/petstore.yaml \
    -g go \
    -o /local/out/go

The generated code will be located under ./out/go in the current directory.

⁠OpenAPI Generator Online Docker Image

The openapi-generator-online image can act as a self-hosted web application and API for generating code. This container can be incorporated into a CI pipeline, and requires at least two HTTP requests and some docker orchestration to access generated code.

Example usage:

# Start container at port 8888 and save the container id
> CID=$(docker run -d -p 8888:8080 openapitools/openapi-generator-online)

# allow for startup
> sleep 10

# Get the IP of the running container (option