Repository files navigation

OpenAPI Generator allows generation of API client libraries (SDK generation), server stubs, documentation andconfiguration automatically given an OpenAPI Spec (both 2.0 and 3.0 are supported). Please seeOpenAPITools/openapi-generator.

The OpenAPI Generator is a Java project.openapi-generator-cli will download the appropriate JAR file and invoke thejava executable to run the OpenAPI Generator. You must have thejava binary executable available on yourPATH for this to work. (JDK 11 is the minimal version supported. To install OpenJDK, please visithttps://adoptium.net/)

If you find this tool useful, please consider sponsoring this project financially viahttps://opencollective.com/openapi_generator or directly toKay Schecker (the author of this tool) 🙏

You need to executeopenapi-generator-cli instead ofopenapi-generator from now on.

To make that happen, a version management was added to the package.The first time you run the commandopenapi-generator-cli the last stable versionofOpenAPITools/openapi-generator is downloaded by default.

That version is saved in the fileopenapitools.json. Therefore, you should include this file in your version control,to ensure that the correct version is being used next time you call the command.

If you would like to use a different version of theOpenAPITools/openapi-generator,you could change it by using one of the following commands:

• openapi-generator-cli version-manager list
• openapi-generator-cli version-manager set <versionTags...>

You will now be able to configure the code generation inopenapitools.json.This makes it more convenient to generate code for every file that matches the given glob expression.For more information,please check out the configuration documentation below.

npm install @openapitools/openapi-generator-cli

or using yarn

yarn add @openapitools/openapi-generator-cli

After the installation has finished you can runnpx openapi-generator-cli or add a script like this:

{"name":"my-cool-package","version":"0.0.0","scripts": {"my-awesome-script-name":"openapi-generator-cli generate -i docs/openapi.yaml -g typescript-angular -o generated-sources/openapi --additional-properties=ngVersion=6.1.7,npmName=restClient,supportsES6=true,npmVersion=6.9.0,withInterfaces=true"  }}

Note the whitespace sensitivity when using multiple additional-properties:

--additional-properties=ngVersion=6.1.7,npmName=restClient,supportsES6=true,npmVersion=6.9.0,withInterfaces=true

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

or using yarn

yarn global add @openapitools/openapi-generator-cli

After the installation has finished you can runopenapi-generator-cli

Mac/Linux:

openapi-generator-cli generate -g ruby -i https://raw.githubusercontent.com/OpenAPITools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml -o /var/tmp/ruby-client

Windows:

openapi-generator-cli generate -g ruby -i https://raw.githubusercontent.com/OpenAPITools/openapi-generator/master/modules/openapi-generator/src/test/resources/3_0/petstore.yaml -o C:\temp\ruby-client

If you have installed the package locally and executed the commandopenapi-generator-cli at least once,you will find a new file calledopenapitools.json along with thepackage.json.Please add this file to your VCS.

Initially the file has the following content:

{"$schema":"node_modules/@openapitools/openapi-generator-cli/config.schema.json","spaces":2,"generator-cli":{"version":"7.8.0"// or the current latest version ;)}}

This configuration indicates the following:

• the json file shall be formatted using2 spaces
• the jar files shall be downloaded to./my/custom/storage/dir
• the generator-cli version 7.8.0 is used

Further it is also possible to configure generators, for example:

{"$schema":"node_modules/@openapitools/openapi-generator-cli/config.schema.json","spaces":2,"generator-cli":{"version":"7.8.0","storageDir":"~/my/custom/storage/dir",// optional"generators":{// optional"v2.0":{// any name you like (just printed to the console log or reference it using --generator-key)"generatorName":"typescript-angular","output":"#{cwd}/output/v2.0/#{ext}/#{name}","glob":"examples/v2.0/{json,yaml}/*.{json,yaml}","additionalProperties":{"ngVersion":"6.1.7","npmName":"restClient","supportsES6":"true","npmVersion":"6.9.0","withInterfaces":true}},"v3.0":{// any name you like (just printed to the console log or reference it using --generator-key)"generatorName":"typescript-fetch","output":"#{cwd}/output/v3.0/#{ext}/#{name}","glob":"examples/v3.0/petstore.{json,yaml}"}}}}

Ifopenapi-generator-cli generate is called without further arguments, then the configurationis automatically used to generate your code. 🎉

If you're using a private maven registry you can configure thedownloadUrl andqueryUrl like this:

{"$schema":"node_modules/@openapitools/openapi-generator-cli/config.schema.json","spaces":2,"generator-cli": {"version":"7.8.0","repository": {"queryUrl":"https://private.maven.intern/solrsearch/select?q=g:${group.id}+AND+a:${artifact.id}&core=gav&start=0&rows=200","downloadUrl":"https://private.maven.intern/maven2/${groupId}/${artifactId}/${versionName}/${artifactId}-${versionName}.jar"    }  }}

If theversion property param is set it is not necessary to configure thequeryUrl.

queryUrl anddownloadUrl can use the following placeholders:

In order to use a locally built jar of the generator CLI, you can copy the jar from your local build (i.e. if you were tobuild theOpenAPITools/openapi-generator repository it would be in~/openapi-generator/modules/openapi-generator-cli/target/openapi-generator-cli.jar) into./node_modules/@openapitools/openapi-generator-cli/versions/ and change theversion in theopenapitools.json file to the base name of the jar file.E.g.:

cd openapi-generator./mvnw clean packagecp ./modules/openapi-generator-cli/target/openapi-generator-cli.jar /your/project/node_modules/@openapitools/openapi-generator-cli/versions/my-local-snapshot.jar

and then:

{"$schema":"./node_modules/@openapitools/openapi-generator-cli/config.schema.json","spaces":2,"generator-cli": {"version":"my-local-snapshot"  }}

Change youropenapitools.json to:

{"$schema":"node_modules/@openapitools/openapi-generator-cli/config.schema.json","spaces":2,"generator-cli": {"version":"7.17.0-20251003.020930-8","repository": {"downloadUrl":"https://central.sonatype.com/repository/maven-snapshots/org/openapitools/openapi-generator-cli/7.17.0-SNAPSHOT/openapi-generator-cli-${version}.jar"    }  }}

Example is with a snapshot of7.17.0, please change theversion anddownloadUrl accordingly.You can find the published snapshots in the build log of thePublish to Maven Central GitHub workflow in OpenAPI Generator repo, e.g.

[INFO] Uploading to central: https://central.sonatype.com/repository/maven-snapshots/org/openapitools/openapi-generator-cli/7.17.0-SNAPSHOT/openapi-generator-cli-7.17.0-20251003.020930-8.jar

{"$schema":"node_modules/@openapitools/openapi-generator-cli/config.schema.json","spaces":2,"generator-cli": {"useDocker":true  }}

IfuseDocker option is used, the spec file gets mounted to path/local/<your-spec-file-location> within container. So, if you would configure spec file as-i openapi/my-api.yml if running locally, with useDocker option set, you would have to configure it like this:-i /local/openapi/my-api.yml.

Custom generators can be used by passing the--custom-generator=/my/custom-generator.jar argument.

To bypass maven repo search for all stable versions (as central.sonatype.com or search.maven.org could be down due to various reasons), one can set the environment variableOPENAPI_GENERATOR_CLI_SEARCH_URL toDEFAULT:

Linux:export OPENAPI_GENERATOR_CLI_SEARCH_URL=DEFAULT

DOS:set OPENAPI_GENERATOR_CLI_SEARCH_URL=DEFAULT

Please refer to theofficial openapi-generator docs formore information about the possible arguments and a detailed usage manual of the command line interface.

npm install @openapitools/openapi-generator-cli@previousnpm i @openapitools/openapi-generator-cli@1.0.18-4.3.1

or using yarn

yarn add @openapitools/openapi-generator-cli@previousyarn add @openapitools/openapi-generator-cli@1.0.18-4.3.1

Please leave a star.