gem-hunter
Language: TypeScript
A node package wrapper for https://github.com/OpenAPITools/openapi-generator
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). Please see OpenAPITools/openapi-generator.
The OpenAPI Generator is a Java project. openapi-generator-cli will download the appropriate JAR file and invoke the java executable to run the OpenAPI Generator. You must have the java binary executable available on your PATH for this to work. (JDK 11 is the minimal version supported. To install OpenJDK, please visit https://adoptium.net/)
If you find this tool useful, please consider sponsoring this project financially via https://opencollective.com/openapi_generator or directly to Kay Schecker (the author of this tool) 🙏
You need to execute openapi-generator-cli instead of openapi-generator from now on.
To make that happen, a version management was added to the package.
The first time you run the command openapi-generator-cli the last stable version
of OpenAPITools/openapi-generator is downloaded by default.
That version is saved in the file openapitools.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 the OpenAPITools/openapi-generator, you can use one of the following commands:
openapi-generator-cli version-manager listopenapi-generator-cli version-manager set <versionTags...>openapi-generator-cli version-manager resolve <versionTags...>The list and set commands can be used to inspect or change the configured version.
The resolve command prints the matching version without downloading a generator or modifying openapitools.json.
You will now be able to configure the code generation in openapitools.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 run npx 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 run openapi-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 command openapi-generator-cli at least once,
you will find a new file called openapitools.json along with the package.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:
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}" } } } }
If openapi-generator-cli generate is called without further arguments, then the configuration
is automatically used to generate your code. 🎉
| placeholder | description | example |
|---|---|---|
| name | just file name | auth |
| Name | just file name, but starting with a capital letter | Auth |
| cwd | the current cwd | /Users/some-user/projects/some-project |
| base | file name and extension | auth.yaml |
| path | full path and filename | /Users/some-user/projects/some-project/docs/auth.yaml |
| dir | path without the filename | /Users/some-user/projects/some-project/docs |
| relDir | directory name of file relative to the glob provided | docs |
| relPath | file name and extension of file relative to the glob provided | docs/auth.yaml |
| ext | just file extension | yaml |
| env. | environment variable (use ${env.name} syntax) |
If you're using a private maven registry you can configure the downloadUrl and queryUrl 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 the version property param is set it is not necessary to configure the queryUrl.
queryUrl and downloadUrl can use the following placeholders:
| placeholder | description |
|---|---|
| groupId | maven groupId where '.' has been replaced with / |
| artifactId | maven artifactId where '.' has been replace with / |
| versionName | maven version (only for downloadUrl) |
| group.id | maven groupId |
| artifact.id | maven artifactId |
| env. | environment variable name |
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 to build the OpenAPITools/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 the version in the openapitools.json file to the base name of the jar file.
E.g.:
cd openapi-generator
./mvnw clean package
cp ./modules/openapi-generator-cli/target/openapi-generator-cli.jar /your/project/node_modules/@openapitools/openapi-generator-cli/versions/my-local-snapshot.jarand then:
{
"$schema": "./node_modules/@openapitools/openapi-generator-cli/config.schema.json",
"spaces": 2,
"generator-cli": {
"version": "my-local-snapshot"
}
}Change your openapitools.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 of 7.17.0, please change the version and downloadUrl accordingly.
You can find the published snapshots in the build log of the Publish 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
| cmd | v3.0 runs | v2.0 runs |
|---|---|---|
| openapi-generator-cli generate --generator-key v3.0 | yes | no |
| openapi-generator-cli generate --generator-key v3.0 v2.0 | yes | yes |
| openapi-generator-cli generate --generator-key foo | no | no |
{
"$schema": "node_modules/@openapitools/openapi-generator-cli/config.schema.json",
"spaces": 2,
"generator-cli": {
"useDocker": true
}
}If useDocker 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 variable OPENAPI_GENERATOR_CLI_SEARCH_URL to DEFAULT:
Linux: export OPENAPI_GENERATOR_CLI_SEARCH_URL=DEFAULT
DOS: set OPENAPI_GENERATOR_CLI_SEARCH_URL=DEFAULT
Please refer to the official openapi-generator docs for more information about the possible arguments and a detailed usage manual of the command line interface.
npm install @openapitools/openapi-generator-cli@previous npm i @openapitools/openapi-generator-cli@1.0.18-4.3.1
or using yarn
yarn add @openapitools/openapi-generator-cli@previous yarn add @openapitools/openapi-generator-cli@1.0.18-4.3.1
Please leave a star.