Tino Fuhrmann ff68128c15
[TypeScript] Rewritten TypeScript client generator supporting fetch & jquery (#6341)
* Added http module draft

* Added generic enum

* Modified http lib, added config & middleware definition to ts-fetch

* Added model generation with imports

* Added auth module

* Added servers

* Added sample for typescript client

* WIP: Models & API

* Updated auth

* WIP: api modeling

* Implemented RequestFactory and Processor completely

* Implemented fetch client

* Ignore dist folder in typescript client sample

* Added middleware to fetch

* Restructured TypeScript generator

* Reverted: http library.send returns string again

* Removed TODOs

* Added pom.xml files to TypeScript PetStore client samples

* Removed tabs from TypeScriptClientCodegen

* Added ts client codegen to root pom.xml and travis

* Added server variable configuration to ts-refactor

* [TS-Refactor] Added tests for Object Serializer

* Added simple test for PetApi

* Fixed ObjectSerializer test

* Added handling for different http status codes and test for deletePet

* Removed tabs in TypeScriptClientCodegen

* Removed tabs in DefaultCodegen

* Additional tests for pet store api

* Fixed file uploads

* Made api call configuration separately settable

* Use string union for enums

* Remove tab

* Restructured module layout

* Use observables internally

* Added promise based middleware

* Made discriminator and attributeTypeMap readonly

* Configure discriminator correctly

* Set discriminator value automatically

* Fixed date-time and date handling

* Added comments & license info

* Added comments

* Ignore openapi-generator-cli/bin

* Removed accidentally created generated code

* Fixed compilation issues in TypeScriptClientCodegen

* Added typescript to docs/generators

* Updated docs

* Added gitignore and git_push

* Added jquery library

* Added pom.xmls, fixed packagejsons and hopefully webppack

* Removed tabs in TypeScriptClientCodegen

* Fixed a couple issues with pom.xml

* Ensured up to date

* Fixed missing fetch definition in TS default tests

* Updated typescript docs

* Refactor typescript merge master (#4319)

Merge master into ts-refactor

* Typescript refactor: stub rxjs (#4424)

* Remove unused supportsES6 field from codegen

* Add a new switch for RXJS

* Remove redundant npm dependency on rxjs4 types

* Fix return type of PromiseMiddleware methods

* Install webpack dependency to run jquery tests

* Update form-data to 2.5 which includes typings

* Add missing dependency on node typings

* Fix test artifact name typo

* Stub rxjs when it is not explicitly enabled

* Typescript refactor: Platform select for browser and node (#4500)

* Use string form of filename parameter

This works for the form-data library and is also compatible with the
browser FormData object.

* Add new option to select platform node or browser

When no platform is selected, a default is chosen by the framework
option and likewise the file data type option is implied by the
platform.

* Remove redundant import of node dns module

* Only use form-data library for node platform

* Generate npm package from npmName option

* Use method convertPropertyToBooleanAndWriteBack

* Generate typescript samples with ensure-up-to-date

* Removed tab from DefaultCodegen

* Readded missing change

* Mark typescript client codegen as experimental

* Removed whitespace

* [TS-Refactor] Top-level exports for fetch & jquery (#6138)

* Added top-level exports
* Updated generator README
* Updated typescript generator docs

* Allow browsers File type for files (#5521)

* Allow passing file parameters as File objects
* Add test for jquery upload
* Use HttpFile object for node platform
* Regenerate samples

This is by far the most common use case. A `File` object already
contains the name attribute. This commit allows that information to be
used directly.
When sending a `Blob`, in most browsers the `File` constructor can be
used to assign a file name. In all other browsers the alternative is
```typescript
Object.assign(data, { name: "foobar.txt" });
```
That is why we explicitely pass the name as third parameter to
`FormData.append`. This `Object.assign` method also works for `Buffer`
objects in node.

If one really does not want to touch the data object in the browser it
is possible to define another reference to the data with
```typescript
new Blob([data], { type: data.type })
```
or in node via
```typescript
Buffer.from(data)
```

* [TS-Refactor] Added options for npm version, repository, name and updated readme (#6139)

* Added options for npm version, repository, name and updated readme

* Removed `this`  where not required

* Updated typescript docs

* Typescript refactor fixes (#6027)

Fixes a handful of issues identified in https://github.com/OpenAPITools/openapi-generator/issues/802#issuecomment-617262139

List of changes

* Clean: Remove redundant cliOption definition

* Remove redundant directory structure in templates

If we need to have different index.ts files for the different
frameworks, we can mostly do that in the one mustache file. In the cases
where that is not possible, we can still add a new override file later.

* Use File.separator consistently

* Only export selected api type

* Simplify promise polyfill import

The behaviour should be the same, according to the es6-promise docs.
Previously tsc would report the error:
> error TS2307: Cannot find module 'es6-promise'.

* Import HttpFile in all models

* Export server configurations

* Use undefined as default body value

The empty string is not interpreted as "no body" by the browser fetch
api and thus leads to an exception during get requests

* Improve codestyle: prefer guards to nesting

* Remove verbose debug output

This should not be commited, because every developer has very different
requirements what debug information he needs to see.

* Fix: Use cleaned model names for imports

* Fix: do not call toString on undefined

* Fix typo in doc comment

* Introduce RequestBody type and remove method check

* Support media types other than json (#6177)

List of changes:

* Add */* as fallback to accept header

* Use more sophisticated media type selection

* Handle object stringify in ObjectSerializer

* Parse response with ObejctSerializer

* Fix: Correctly extract response headers in browser

* Create HttpFile objects from responses

* Handle binary responses

* Clean up dependencies and replace isomorphic-fetch

Instead of isomorphic-fetch, which is unmaintained, we directly use
node-fetch and whatwg-fetch polyfills.

* Updated versions in ts-default/jquery and ts docs

* Replaced isSuccessCode with is2xx

* [TypeScript-Refactor] Use OAIv3 spec and fix bugs in JQuery Blob download (#6416)

* Change to OAIv3 spec for TS-Refactor

* Moved samples to oaiv3 folder

* Updated package-lock

* Update pom to use OAIv3 paths for Typescript-refactor

* Renamed ts-refactor samples & tests in pom.xmls

* Fixed compile issues in ts-refactor jquery http test

* Fixed bugs in blob handling of jquery

* [Typescript] Support http bearer authentication with token provider (#6425)

* Add http bearer security

* Update typescript to 3.9

* Fix: Use Authorization header for basic and bearer

* Allow asynchronous tokenProvider in bearer auth

* Add TS-Rewrite-Jquery tests node_modules to travis caching

* Remove NoAuthentication

* Added file to generate TS samples on Windows

* Exclude btoa in browser

* Regen samples

* Remove outdated ToDo comments

* Document and optimize `getReturnType` in TSClientCodegen

* Added option to generate objects for operation function arguments

* Upgrade typescript docs

* Updated generators

* Updated samples

* Updated docs

* Readded pom.xml

* [Typescript] Support InversifyJS (#6489)

* Add config option to enable InversifyJS

* Add pascal case lambda for mustache

* Generate a class for each auth method

* Add service identifiers and service binder helper

* Split Configuration into interface and factory

This way we don't need to import the factory everywhere to do
typechecking.

* Define minimal interface for ServerConfiguration

* Add annotations for inversify when enabled

* Always expose list of server configurations

* Add samples and defalt tests for useInversify

* Simplify sample generation script

* Fix: Add object_params arg description to help

* Fix: Properly enable inversify with bool property

* Build tests in pom instead of prepublish

Otherwise running `npm install`, when the build failed was impossible.

* Update dependencies for inversify tests

* Test basic api service resolution

* Remove Promise and Observable prefix from exports

* Fix, RxJS: Import Observable in object params api

* Add ioc service identifier for object param api

* Add hint about unimpeded development

* Simplify api service binder syntax

* Remove default tests for inversify

* Add wrapper for easy promise based http libraries

This wrapper allows defining and injecting http libraries that do not
need to know anything about observables, especially when useRxJS is not
enabled. I will employ this in the tests for InversifyJS.

Not sure if we should also use this wrapper internally.

* Add named injects for remaining auth parameters

* Directly inject promise services without RxJS

* Add tests for api service binder

* Add convenience method to bind all api services

* Fix: Rename inversify test artifact

* Run bin/utils/copy-to-website.sh

* Restore changes to CONTRIBUTING.md from PR #6489

Co-authored-by: Bodo Graumann <mail@bodograumann.de>
Co-authored-by: Esteban Gehring <esteban.gehring@bithost.ch>
2020-06-15 08:12:39 +02:00
2020-02-20 09:25:11 +08:00
2019-06-06 15:09:26 -04:00
2018-05-11 15:28:32 +08:00
2020-06-15 10:47:25 +08:00

OpenAPI Generator

Master (5.0.0): Build Status Integration Test2 Run Status Windows Test JDK11 Build iOS Build Status

Jion the Slack chat room Stable releaases in the Maven store Follow OpenAPI Generator Twitter account to get the latest update

If you would like to contribute, please refer to guidelines and a list of open tasks.

‼️ To migrate from Swagger Codegen to OpenAPI Generator, please refer to the migration guide ‼️

📔 For more information, please refer to the Wiki page and FAQ 📔

📔 The eBook A Beginner's Guide to Code Generation for REST APIs is a good starting point for beginners 📔

⚠️ 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) ⚠️

‼️ Both "OpenAPI Tools" (https://OpenAPITools.org - the parent organization of OpenAPI Generator) and "OpenAPI Generator" are not affiliated with OpenAPI Initiative (OAI) ‼️

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!

NamSor LightBow

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

Linode

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.0, .NET Core 2.0), C++ (cpp-restsdk, Qt5, Tizen), Clojure, Dart (1.x, 2.x), Elixir, Elm, Eiffel, Erlang, Go, Groovy, Haskell (http-client, Servant), Java (Jersey1.x, Jersey2.x, OkHttp, Retrofit1.x, Retrofit2.x, Feign, RestTemplate, RESTEasy, Vertx, Google API Client Library for Java, Rest-assured, Spring 5 Web Client, MicroProfile Rest Client), k6, Kotlin, Lua, 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 (rust, rust-server), Scala (akka, http4s, scalaz, sttp, swagger-async-httpclient), Swift (2.x, 3.x, 4.x, 5.x), Typescript (AngularJS, Angular (2.x - 8.x), Aurelia, Axios, Fetch, Inversify, jQuery, Node, Rxjs)
Server stubs Ada, C# (ASP.NET Core, NancyFx), C++ (Pistache, Restbed, Qt5 QHTTPEngine), Erlang, F# (Giraffe), Go (net/http, Gin), Haskell (Servant), Java (MSF4J, Spring, Undertow, JAX-RS: CDI, CXF, Inflector, Jersey, RestEasy, Play Framework, PKMST, Vert.x), Kotlin (Spring Boot, Ktor, Vertx), PHP (Laravel, Lumen, Slim, Silex, Symfony, Zend Expressive), Python (Flask), NodeJS, Ruby (Sinatra, Rails5), Rust (rust-server), Scala (Akka, Finch, Lagom, Play, Scalatra)
API documentation generators HTML, Confluence Wiki, Asciidoc
Configuration files Apache2
Others GraphQL, JMeter, MySQL Schema, Protocol Buffer

Table of contents

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 Generator Version Release Date Notes
5.0.0 (upcoming major release) SNAPSHOT 17.06.2020 Major release with breaking changes (no fallback)
4.3.1 (latest stable release) 06.05.2020 Patch release (enhancements, bug fixes, etc)

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>

Gradle plugin:

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

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/4.3.1/openapi-generator-cli-4.3.1.jar

For Mac/Linux users:

wget https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/4.3.1/openapi-generator-cli-4.3.1.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/4.3.1/openapi-generator-cli-4.3.1.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:

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

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 (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/2_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 /gen/bin/go-petstore.sh  # Builds the Go client
./run-in-docker.sh generate -i modules/openapi-generator/src/test/resources/2_0/petstore.yaml \
    -g go -o /gen/out/go-petstore -DpackageName=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

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 version

Or install a particular OpenAPI Generator version (e.g. v4.3.1):

npm install @openapitools/openapi-generator-cli@cli-4.3.1 -g

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
mvn 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/2_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/2_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

3 - Usage

To generate a sample client library

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

./bin/java-petstore-okhttp-gson.sh

(On Windows, run .\bin\windows\java-petstore-okhttp-gson.bat instead)

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/2_0/petstore.yaml \
  -g java \
  -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>)]
                [-D <system properties>...]
                [(-e <templating engine> | --engine <templating engine>)]
                [--enable-post-process-file]
                [(-g <generator name> | --generator-name <generator name>)]
                [--generate-alias-as-model] [--git-repo-id <git repo id>]
                [--git-user-id <git user id>] [--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>...]
                [--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 languages have petstore samples, too:

./bin/android-petstore-all.sh
./bin/java-petstore-all.sh
./bin/objc-petstore.sh

... and others. Here is a list of all scripts.

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:

The server is sponsored by Linode Linode Logo

(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.4 - License information on Generated Code

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.

3.5 - IDE Integration

Here is a list of community-conitributed IDE plug-ins that integrate with OpenAPI Generator:

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.

5 - Presentations/Videos/Tutorials/Books

6 - About Us

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.

Core Team Members

❤️ = Link to support the contributor directly

Template Creator

NOTE: Embedded templates are only supported in Mustache format. Support for all other formats is experimental and subject to change at any time.

Here is a list of template creators:

  • API Clients:
    • Ada: @stcarrez
    • Apex: @asnelling
    • Bash: @bkryza
    • C: @PowerOfCreation @zhemant ❤️
    • C++ REST: @Danielku15
    • C++ UE4: @Kahncode
    • C# (.NET 2.0): @who
    • C# (.NET Standard 1.3 ): @Gronsak
    • C# (.NET 4.5 refactored): @jimschubert ❤️
    • Clojure: @xhh
    • Dart: @yissachar
    • Dart (refactor): @joernahrens
    • Dart 2: @swipesight
    • Dart (Jaguar): @jaumard
    • Dart (Dio): @athornz
    • Elixir: @niku
    • Elm: @eriktim
    • Eiffel: @jvelilla
    • Erlang: @tsloughter
    • Erlang (PropEr): @jfacorro @robertoaloi
    • Groovy: @victorgit
    • Go: @wing328 ❤️
    • Go (rewritten in 2.3.0): @antihax
    • Haskell (http-client): @jonschoning
    • Java (Feign): @davidkiss
    • Java (Retrofit): @0legg
    • Java (Retrofit2): @emilianobonassi
    • Java (Jersey2): @xhh
    • Java (okhttp-gson): @xhh
    • Java (RestTemplate): @nbruno
    • Java (Spring 5 WebClient): @daonomic
    • Java (RESTEasy): @gayathrigs
    • Java (Vertx): @lopesmcc
    • Java (Google APIs Client Library): @charlescapps
    • Java (Rest-assured): @viclovsky
    • Java (Java 11 Native HTTP client): @bbdouglas
    • Javascript/NodeJS: @jfiala
    • Javascript (Apollo DataSource): @erithmetic
    • Javascript (Closure-annotated Angular) @achew22
    • Javascript (Flow types) @jaypea
    • JMeter: @davidkiss
    • Kotlin: @jimschubert ❤️
    • Kotlin (MultiPlatform): @andrewemery
    • Lua: @daurnimator
    • Nim: @hokamoto
    • OCaml: @cgensoul
    • Perl: @wing328 ❤️
    • PHP (Guzzle): @baartosz
    • PowerShell: @beatcracker
    • PowerShell (refactored in 5.0.0): @wing328
    • Python-experimental: @spacether
    • R: @ramnov
    • Ruby (Faraday): @meganemura @dkliban
    • Rust: @farcaller
    • Rust (rust-server): @metaswitch
    • Scala (scalaz & http4s): @tbrown1979
    • Scala (Akka): @cchafer
    • Scala (sttp): @chameleon82
    • Swift: @tkqubo
    • Swift 3: @hexelon
    • Swift 4: @ehyche
    • Swift 5: @4brunu
    • TypeScript (Angular1): @mhardorf
    • TypeScript (Angular2): @roni-frantchi
    • TypeScript (Angular6): @akehir
    • TypeScript (Angular7): @topce
    • TypeScript (Axios): @nicokoenig
    • TypeScript (Fetch): @leonyu
    • TypeScript (jQuery): @bherila
    • TypeScript (Node): @mhardorf
    • TypeScript (Rxjs): @denyo
    • TypeScript (Inversify): @gualtierim
    • TypeScript (redux-query): @petejohansonxo
  • Server Stubs
    • Ada: @stcarrez
    • C# ASP.NET 5: @jimschubert ❤️
    • C# ASP.NET Core 3.0: @A-Joshi
    • C# APS.NET Core 3.1: @phatcher
    • C# NancyFX: @mstefaniuk
    • C++ (Qt5 QHttpEngine): @etherealjoy
    • C++ Pistache: @sebymiano
    • C++ Restbed: @stkrwork
    • Erlang Server: @galaxie
    • F# (Giraffe) Server: @nmfisher
    • Go Server: @guohuang
    • Go (Gin) Server: @kemokemo
    • GraphQL Express Server: @renepardon
    • Haskell Servant: @algas
    • Java MSF4J: @sanjeewa-malalgoda
    • Java Spring Boot: @diyfr
    • Java Undertow: @stevehu
    • Java Play Framework: @JFCote
    • Java PKMST: @anshu2185 @sanshuman @rkumar-pk @ninodpillai
    • Java Vert.x: @lwlee2608
    • JAX-RS RestEasy: @chameleon82
    • JAX-RS CXF: @hiveship
    • JAX-RS CXF (CDI): @nickcmaynard
    • JAX-RS RestEasy (JBoss EAP): @jfiala
    • Kotlin: @jimschubert ❤️
    • Kotlin (Spring Boot): @dr4ke616
    • Kotlin (Vertx): @Wooyme
    • NodeJS Express: @YishTish
    • PHP Laravel: @renepardon
    • PHP Lumen: @abcsun
    • PHP Slim: @jfastnacht
    • PHP Symfony: @ksm2
    • PHP Zend Expressive (with Path Handler): @Articus
    • Python AIOHTTP: @Jyhess
    • Ruby on Rails 5: @zlx
    • Rust (rust-server): @metaswitch
    • Scala Akka: @Bouillie
    • Scala Finch: @jimschubert ❤️
    • Scala Lagom: @gmkumar2005
    • Scala Play: @adigerber
  • Documentation
    • AsciiDoc: @man-at-home
    • HTML Doc 2: @jhitchcock
    • Confluence Wiki: @jhitchcock
    • PlantUML: @pburls
  • Configuration
    • Apache2: @stkrwork
    • k6: @mostafa
  • Schema
    • Avro: @sgadouar
    • GraphQL: @wing328 ❤️
    • MySQL: @ybelenko
    • Protocol Buffer: @wing328

❤️ = Link to support the contributor directly

How to join the core team

Here are the requirements to become a core team member:

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.

Members of Technical Committee

Languages Member (join date)
ActionScript
Ada @stcarrez (2018/02) @michelealbano (2018/02)
Android @jaz-ah (2017/09)
Apex
Bash @frol (2017/07) @bkryza (2017/08) @kenjones-cisco (2017/09)
C @zhemant (2018/11) @ityuhui (2019/12) @michelealbano (2020/03)
C++ @ravinikam (2017/07) @stkrwork (2017/07) @etherealjoy (2018/02) @martindelille (2018/03) @muttleyxd (2019/08)
C# @mandrean (2017/08), @jimschubert (2017/09) ❤️ @frankyjuang (2019/09) @shibayan (2020/02)
Clojure
Dart @ircecho (2017/07) @swipesight (2018/09) @jaumard (2018/09) @athornz (2019/12) @amondnet (2019/12)
Eiffel @jvelilla (2017/09)
Elixir @mrmstn (2018/12)
Elm @eriktim (2018/09)
Erlang @tsloughter (2017/11) @jfacorro (2018/10) @robertoaloi (2018/10)
F# @nmfisher (2019/05)
Go @antihax (2017/11) @bvwells (2017/12) @grokify (2018/07) @kemokemo (2018/09) @bkabrda (2019/07)
GraphQL @renepardon (2018/12)
Groovy
Haskell
Java @bbdouglas (2017/07) @sreeshas (2017/08) @jfiala (2017/08) @lukoyanov (2017/09) @cbornet (2017/09) @jeff9finger (2018/01) @karismann (2019/03) @Zomzog (2019/04) @lwlee2608 (2019/10) @bkabrda (2020/01)
Kotlin @jimschubert (2017/09) ❤️, @dr4ke616 (2018/08) @karismann (2019/03) @Zomzog (2019/04) @andrewemery (2019/10) @4brunu (2019/11) @yutaka0m (2020/03)
Lua @daurnimator (2017/08)
Nim
NodeJS/Javascript @CodeNinjai (2017/07) @frol (2017/07) @cliffano (2017/07)
ObjC
OCaml @cgensoul (2019/08)
Perl @wing328 (2017/07) ❤️ @yue9944882 (2019/06)
PHP @jebentier (2017/07), @dkarlovi (2017/07), @mandrean (2017/08), @jfastnacht (2017/09), @ackintosh (2017/09) ❤️, @ybelenko (2018/07), @renepardon (2018/12)
PowerShell @wing328 (2020/05)
Python @taxpon (2017/07) @frol (2017/07) @mbohlool (2017/07) @cbornet (2017/09) @kenjones-cisco (2017/11) @tomplus (2018/10) @Jyhess (2019/01) @arun-nalla (2019/11) @spacether (2019/11)
R @Ramanth (2019/07) @saigiridhar21 (2019/07)
Ruby @cliffano (2017/07) @zlx (2017/09) @autopp (2019/02)
Rust @frol (2017/07) @farcaller (2017/08) @bjgill (2017/12) @richardwhiuk (2019/07) @paladinzh (2020/05)
Scala @clasnake (2017/07), @jimschubert (2017/09) ❤️, @shijinkui (2018/01), @ramzimaalej (2018/03), @chameleon82 (2020/03), @Bouillie (2020/04)
Swift @jgavris (2017/07) @ehyche (2017/08) @Edubits (2017/09) @jaz-ah (2017/09) @4brunu (2019/11)
TypeScript @TiFu (2017/07) @taxpon (2017/07) @sebastianhaas (2017/07) @kenisteward (2017/07) @Vrolijkx (2017/09) @macjohnny (2018/01) @topce (2018/10) @akehir (2019/07) @petejohansonxo (2019/11) @amakhrov (2020/02)

❤️ = Link to support the contributor directly

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.

Founding Members (alphabetical order):

❤️ = Link to support the contributor directly

7 - License


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.


Description
OpenAPI Generator allows generation of API client libraries (SDK generation), server stubs, documentation and configuration automatically given an OpenAPI Spec (v2, v3)
Readme Apache-2.0 1.2 GiB
Languages
Java 93.3%
TypeScript 2.1%
Kotlin 1.3%
Shell 1.1%
Handlebars 0.5%
Other 1.4%