Master (7.28.0):
:star::star::star: If you would like to contribute, please refer to guidelines and a list of open tasks. :star::star::star:
:bangbang: To migrate from Swagger Codegen to OpenAPI Generator, please refer to the migration guide :bangbang:
:notebook_with_decorative_cover: For more information, please refer to the Wiki page and FAQ :notebook_with_decorative_cover:
:notebook_with_decorative_cover: The eBook A Beginner's Guide to Code Generation for REST APIs is a good starting point for beginners :notebook_with_decorative_cover:
:warning: If the OpenAPI spec, templates or any input (e.g. options, environment variables) is obtained from an untrusted source or environment, please make sure you've reviewed these inputs before using OpenAPI Generator to generate the API client, server stub or documentation to avoid potential security issues (e.g. code injection). For security vulnerabilities, please contact [email protected]. :warning:
:bangbang: Both "OpenAPI Tools" (https://OpenAPITools.org - the parent organization of OpenAPI Generator) and "OpenAPI Generator" are not affiliated with OpenAPI Initiative (OAI) :bangbang:
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, Checkly for sponsoring the API monitoring and Gradle for sponsoring Develocity
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:
| Languages/Frameworks |
|---|
| API clients | ActionScript, Ada, Apex, Bash, C, C# (.net 2.0, 3.5 or later, .NET Standard 1.3 - 2.1, .NET Core 3.1, .NET 5.0. Libraries: RestSharp, GenericHost, HttpClient), C++ (Arduino, cpp-restsdk, Qt5, Tizen, Unreal Engine 4), Clojure, Crystal, Dart, Elixir, Elm, Eiffel, Erlang, Go, Groovy, Haskell (http-client, Servant), Java (Apache HttpClient 4.x, Apache HttpClient 5.x, Jersey2.x, OkHttp, Retrofit1.x, Retrofit2.x, Feign, RestTemplate, RESTEasy, Vertx, Google API Client Library for Java, Rest-assured, Spring 5 Web Client, Spring 6 RestClient, MicroProfile Rest Client, Helidon), Jetbrains HTTP Client, Julia, k6, Kotlin, Lua, N4JS, Nim, Node.js/JavaScript (ES5, ES6, AngularJS with Google Closure Compiler annotations, Flow types, Apollo GraphQL DataStore), Objective-C, OCaml, Perl, PHP, PowerShell, Python, R, Ruby, Rust (hyper, reqwest, rust-server), Scala (akka, http4s, scalaz, sttp, swagger-async-httpclient, pekko), Swift (2.x, 3.x, 4.x, 5.x, 6.x), Typescript (AngularJS, Angular (9.x - 19.x), Aurelia, Axios, Fetch, Inversify, jQuery, Nestjs, Node, redux-query, Rxjs), XoJo, Zapier |
| Server stubs | Ada, C# (ASP.NET Core, Azure Functions), C++ (Httplib, Oat++, Pistache, Restbed, Qt5 QHTTPEngine), Erlang, F# (Giraffe), Go (net/http, Gin, Echo), Haskell (Servant, Yesod), Java (MSF4J, Spring, Undertow, JAX-RS: CDI, CXF, Inflector, Jersey, RestEasy, Play Framework, PKMST, Vert.x, Apache Camel, Helidon), Julia, Kotlin (Spring Boot, Ktor, Vert.x), PHP (Flight, Laravel, Lumen, Mezzio (fka Zend Expressive), Slim, Silex, Symfony), Python (FastAPI, Flask), NodeJS, Ruby (Sinatra, Rails5), Rust (rust-server), Scala (Akka, Finch, Lagom, Play, Cask, Scalatra) |
| API documentation generators | HTML, Confluence Wiki, Asciidoc, Markdown, PlantUML |
| Configuration files | Apache2 |
| Others | GraphQL, JMeter, Ktorm, MySQL Schema, Postman Collection, Protocol Buffer, WSDL |
Table of contents
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 Generator Version | Release Date | Notes |
|---|
| 7.28.0 (upcoming minor release) SNAPSHOT | 20.11.2026 | Minor release with breaking changes (with fallback) |
| 7.27.0 (latest stable release) | 02.11.2026 | Minor release with breaking changes (with fallback) |
| 6.6.0 | 11.05.2023 | Minor release with breaking changes (with fallback) |
| 5.4.0 | 31.01.2022 | Minor release with breaking changes (with fallback) |
| 4.3.1 | 06.05.2020 | Patch release (enhancements, bug fixes, etc) |
OpenAPI Spec compatibility: 1.0, 1.1, 1.2, 2.0, 3.0, 3.1 (beta support)
(We do not publish daily/nightly build. Please use SNAPSHOT instead)
For old releases, please refer to the Release page.
For decommissioned generators/libraries/frameworks, please refer to the "Decommission" label in the pull request page.
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>
Gradle plugin:
<dependency>
<groupId>org.openapitools</groupId>
<artifactId>openapi-generator-gradle-plugin</artifactId>
<version>${openapi-generator-version}</version>
</dependency>
If you're looking for the latest stable version, you can grab it directly from Maven.org (Java 11 runtime at a minimum):
JAR location: https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/7.27.0/openapi-generator-cli-7.27.0.jar
For Mac/Linux users:
wget https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/7.27.0/openapi-generator-cli-7.27.0.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/7.27.0/openapi-generator-cli-7.27.0.jar
After downloading the JAR, run java -jar openapi-generator-cli.jar help to show the usage.
For Mac users, please make sure Java 11 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.11`
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 4.1.0 for the current invocation, regardless of the latest released version
OPENAPI_GENERATOR_VERSION=4.1.0 openapi-generator-cli version
# Execute version 4.1.0-SNAPSHOT for the current invocation
OPENAPI_GENERATOR_VERSION=4.1.0-SNAPSHOT openapi-generator-cli version
# Execute version 4.0.2 for every invocation in the current shell session
export OPENAPI_GENERATOR_VERSION=4.0.2
openapi-generator-cli version # is 4.0.2
openapi-generator-cli version # is also 4.0.2
# To "install" a specific version, set the variable in .bashrc/.bash_profile
echo "export OPENAPI_GENERATOR_VERSION=4.0.2" >> ~/.bashrc
source ~/.bashrc
openapi-generator-cli version # is always 4.0.2, unless any of the above overrides are done ad hoc
To build from source, you need the following installed and available in your $PATH:
After cloning the project, you can build it from source using maven wrapper:
- Linux:
./mvnw clean install
- Windows:
mvnw.cmd clean install
Nix users
If you're a nix user, you can enter OpenAPI Generator shell, by typing:
nix develop
It will enter a shell with Java 11 installed.
Direnv supports automatically loading of the nix developer shell, so if you're using direnv too, type:
direnv allow
and have java and mvn set up with correct versions each time you enter project directory.
The default build contains minimal static analysis (via CheckStyle). To run your build with PMD and Spotbugs, use the static-analysis profile:
- Linux:
./mvnw -Pstatic-analysis clean install
- Windows:
mvnw.cmd -Pstatic-analysis clean install
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/3_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 install --cask adoptopenjdk11
export JAVA_HOME=`/usr/libexec/java_home -v 1.11`
or download installer via https://adoptium.net/
To install Maven (optional), please run
brew install maven
Public Pre-built Docker images
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/3_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 (optional)
GEN_IP=$(docker inspect --format '{{.NetworkSettings.IPAddress}}' $CID)
# Execute an HTTP request to generate a Ruby client
> curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' \
-d '{"openAPIUrl": "https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml"}' \
'http://localhost:8888/api/gen/clients/ruby'
{"code":"c2d483.3.4672-40e9-91df-b9ffd18d22b8","link":"http://localhost:8888/api/gen/download/c2d483.3.4672-40e9-91df-b9ffd18d22b8"}
# Download the generated zip file
> wget http://localhost:8888/api/gen/download/c2d483.3.4672-40e9-91df-b9ffd18d22b8
# Unzip the file
> unzip c2d483.3.4672-40e9-91df-b9ffd18d22b8
# Shutdown the openapi generator image
> docker stop $CID && docker rm $CID
Development in docker
You can use 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/openapitools/openapi-generator
cd openapi-generator
./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-generator-cli. To generate code, you'll need to output to a directory under /gen (e.g. /gen/out). For example:
./run-in-docker.sh help # Executes 'help' command for openapi-generator-cli
./run-in-docker.sh list # Executes 'list' command for openapi-generator-cli
./run-in-docker.sh generate -i modules/openapi-generator/src/test/resources/3_0/petstore.yaml \
-g go -o /gen/out/go-petstore -p packageName=petstore # generates go client, outputs locally to ./out/go-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-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-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 :|
Run Docker in Vagrant
Prerequisite: install Vagrant and VirtualBox.
git clone https://github.com/openapitools/openapi-generator.git
cd openapi-generator
vagrant up
vagrant ssh
cd /vagrant
./run-in-docker.sh mvn package
There is also an NPM package wrapper available for different platforms (e.g. Linux, Mac, Windows). (JVM is still required)
Please see the project's README there for more information.
Install it globally to get the CLI available on the command line:
npm install @openapitools/openapi-generator-cli -g
openapi-generator-cli version
To use a specific version of "openapi-generator-cli"
openapi-generator-cli version-manager set 7.27.0
Or install it as dev-dependency:
npm install @openapitools/openapi-generator-cli -D
You can use locally built JARs or SNAPSHOT versions as well.
Platform(s): Linux, macOS, Windows
Install via PyPI (java executable is needed to run):
pip install openapi-generator-cli
To install a specific version
pip install openapi-generator-cli==7.27.0
You can also install with jdk4py instead of java binary. (python>=3.10 is required)
pip install openapi-generator-cli[jdk4py]
Ref: https://github.com/openAPITools/openapi-generator-pip
To generate a PHP client for petstore.yaml, please run the following
git clone https://github.com/openapitools/openapi-generator
cd openapi-generator
./mvnw clean package
java -jar modules/openapi-generator-cli/target/openapi-generator-cli.jar generate \
-i https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml \
-g php \
-o /var/tmp/php_api_client
(if you're on Windows, replace the last command with java -jar modules\openapi-generator-cli\target\openapi-generator-cli.jar generate -i https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml -g php -o c:\temp\php_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 modules/openapi-generator-cli/target/openapi-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 modules/openapi-generator-cli/target/openapi-generator-cli.jar config-help -g php
To generate a sample client library
You can build a client against the Petstore API as follows:
./bin/generate-samples.sh ./bin/configs/java-okhttp-gson.yaml
(On Windows, please install GIT Bash for Windows to run the command above)
This script uses the default library, which is okhttp-gson. It will run the generator with this command:
java -jar modules/openapi-generator-cli/target/openapi-generator-cli.jar generate \
-i https://raw.githubusercontent.com/openapitools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml \
-g java \
-t modules/openapi-generator/src/main/resources/Java \
--additional-properties artifactId=petstore-okhttp-gson,hideGenerationTimestamp=true \
-o samples/client/petstore/java/okhttp-gson
with a number of options. The java options are documented here.
You can also get the options with the help generate command (below only shows partial results):
NAME
openapi-generator-cli generate - Generate code with the specified
generator.
SYNOPSIS
openapi-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>)]
[--generate-alias-as-model] [--git-host <git host>]
[--git-repo-id <git repo id>] [--git-user-id <git user id>]
[--global-property <global properties>...] [--group-id <group id>]
[--http-user-agent <http user agent>]
[(-i <spec file> | --input-spec <spec file>)]
[--ignore-file-override <ignore file override location>]
[--import-mappings <import mappings>...]
[--instantiation-types <instantiation types>...]
[--invoker-package <invoker package>]
[--language-specific-primitives <language specific primitives>...]
[--legacy-discriminator-behavior] [--library <library>]
[--log-to-stderr] [--minimal-update]
[--model-name-prefix <model name prefix>]
[--model-name-suffix <model name suffix>]
[--model-package <model package>]
[(-o <output directory> | --output <output directory>)] [(-p <additional properties> | --additional-properties <additional properties>)...]
[--package-name <package name>] [--release-note <release note>]
[--remove-operation-id-prefix]
[--reserved-words-mappings <reserved word mappings>...]
[(-s | --skip-overwrite)] [--server-variables <server variables>...]
[--skip-validate-spec] [--strict-spec <true/false strict behavior>]
[(-t <template directory> | --template-dir <template directory>)]
[--type-mappings <type mappings>...] [(-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
...... (results omitted)
-v, --verbose
verbose mode
You can then compile and run the client, as well as unit tests against it:
cd samples/client/petstore/java/okhttp-gson
mvn package
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, sbt, Bazel, Github and CI/CD.
Here are the public online services:
The server is sponsored by Linode 
(These services are beta and do not have any guarantee on service level)
Please refer to online.md on how to run and use the openapi-generator-online - a web service for openapi-generator.
The OpenAPI 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:
- The templates included with this project are subject to the License.
- Generated code is intentionally not subject to the parent project license
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.
Here is a list of community-contributed IDE plug-ins that integrate with OpenAPI Generator:
Here are some companies/projects (alphabetical order) using OpenAPI Generator in production. To add your company/project to the list, please visit README.md and click on the icon to edit the page.
