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
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
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
1.4 - Build Projects
To build from source, you need the following installed and available in your $PATH:
Apache Maven 3.8.8 or greater (optional)
After cloning the project, you can build it from source using maven wrapper:
- Linux:
./mvnw clean install
- Windows:
mvnw.cmd clean install
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/3_0/petstore.yaml \
-g go \
-o /local/out/go
The generated code will be located under ./out/go
in the current directory.
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`: ```sh 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 ./mvnw 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 ./mvnw 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 ./mvnw package
1.7 - NPM
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.0.1
Or install it as dev-dependency:
npm install @openapitools/openapi-generator-cli -D
2 - Getting Started
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.
3.1 - Customization
Please refer to customization.md on how to customize the output (e.g. package name, version)
3.2 - Workflow Integration (Maven, Gradle, Github, CI/CD)
Please refer to integration.md on how to integrate OpenAPI generator with Maven, Gradle, sbt, Bazel, Github and CI/CD.
3.3 - Online OpenAPI generator
Here are the public online services:
- latest stable version: https://api.openapi-generator.tech
- latest master: https://api-latest-master.openapi-generator.tech (updated with latest master every hour)
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
.
3.5 - IDE Integration
Here is a list of community-contributed IDE plug-ins that integrate with OpenAPI Generator:
- Eclipse: Codewind OpenAPI Tools for Eclipse by IBM
- IntelliJ IDEA: OpenAPI Generator by Jim Schubert
- IntelliJ IDEA: Senya Editor by senya.io
- RepreZen API Studio
- Visual Studio: REST API Client Code Generator by Christian Resma Helle
- Visual Studio Code: Codewind OpenAPI Tools by IBM
4 - Companies/Projects using 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.
- Aalborg University
- Adaptant Solutions AG
- adesso SE
- Adyen
- Agoda
- Airthings
- Aleri Solutions Gmbh
- Allianz
- Angular.Schule
- Aqovia
- Australia and New Zealand Banking Group (ANZ)
- Arduino
- ASKUL
- Amazon Web Services (AWS)
- b<>com
- 百度营销
- Bandwidth
- Banzai Cloud
- BIMData.io
- Bithost GmbH
- Bosch Connected Industry
- Boxever
- Brevy
- Bunker Holding Group
- California State University, Northridge
- CAM
- Camptocamp
- Carlsberg Group
- Christopher Queen Consulting
- Cisco
- codecentric AG
- CoinAPI
- Commencis
- cronn GmbH
- Crossover Health
- Cupix
- Datadog
- DB Systel
- Deeporute.ai
- Devsupply
- dmTECH GmbH
- DocSpring
- dwango
- Edge Impulse
- Element AI
- Embotics
- emineo
- fastly
- Fenergo
- freee
- FreshCells
- Fuse
- Gantner
- GenFlow
- GetYourGuide
- Glovo
- GMO Pepabo
- GoDaddy
- Gumtree
- Here
- IBM
- Instana
- Interxion
- Inquisico
- JustStar
- k6.io
- Klarna
- Kronsoft Development
- Kubernetes
- Landeshauptstadt München - it@M
- Linode
- Logicdrop
- Lumeris
- LVM Versicherungen
- MailSlurp
- Manticore Search
- Mastercard
- Médiavision
- Metaswitch
- MoonVision
- Myworkout
- NamSor
- Neverfail
- NeuerEnergy
- Nokia
- OneSignal
- Options Clearing Corporation (OCC)
- Openet
- openVALIDATION
- Oracle
- Paxos
- Plaid
- PLAID, Inc.
- Ponicode
- Pricefx
- PrintNanny
- Prometheus/Alertmanager
- Qavar
- QEDIT
- Qovery
- Qulix Systems
- Raksul
- Raiffeisen Schweiz Genossenschaft
- RedHat
- RepreZen API Studio
- REST United
- Robocorp
- Robotinfra
- SearchApi
- SmartHR
- Sony Interactive Entertainment
- Splitit
- Stingray
- Suva
- Svix
- Telstra
- Tencent
- The University of Aizu
- Translucent ApS
- TravelTime platform
- TribalScale
- Trifork
- TUI InfoTec GmbH
- Twilio
- unblu inc.
- Veamly
- VMWare
- wbt-solutions
- Woleet
- WSO2
- Vouchery.io
- Xero
- Yahoo Japan
- viadee
- Vonage
- YITU Technology
- Yelp
- Zalando
- 3DS Outscale
6.1 - OpenAPI Generator Core Team
OpenAPI Generator core team members are contributors who have been making significant contributions (review issues, fix bugs, make enhancements, etc) to the project on a regular basis.
How to join the core team
Here are the requirements to become a core team member:
- rank within top 50 in https://github.com/openapitools/openapi-generator/graphs/contributors
- to contribute, here are some good starting points
- regular contributions to the project
- about 3 hours per week
- for contribution, it can be addressing issues, reviewing PRs submitted by others, submitting PR to fix bugs or make enhancements, etc
- must be active in the past 3 months at the time of application
To join the core team, please reach out to team@openapitools.org for more information.
To become a Template Creator, simply submit a PR for new API client (e.g. Rust, Elixir) or server stub (e.g. Ruby Grape) generator.
6.2 - OpenAPI Generator Technical Committee
Members of the OpenAPI Generator technical committee shoulder the following responsibilities:
- Provides guidance and direction to other users
- Reviews pull requests and issues
- Improves the generator by making enhancements, fixing bugs or updating documentations
- Sets the technical direction of the generator
Who is eligible? Those who want to join must have at least 3 PRs merged into a generator. (Exceptions can be granted to template creators or contributors who have made a lot of code changes with less than 3 merged PRs)
If you want to join the committee, please kindly apply by sending an email to team@openapitools.org with your Github ID.
6.3 - History of OpenAPI Generator
OpenAPI Generator is a fork of Swagger Codegen. In view of the issues with the Swagger Codegen 3.0.0 (beta) release and the disagreement on the project’s direction, more than 40 top contributors and template creators of Swagger Codegen decided to fork Swagger Codegen and maintain a community-driven version called “OpenAPI Generator”. Please refer to the Q&A for more information.