OpenAPI Generator CLI: Node setup and first generation

Why the Node wrapper exists

OpenAPI Generator CLI addresses the gap between an npm-based development workflow and the underlying OpenAPI Generator, which is a Java project. The package is intended for engineers who want to generate API client libraries, server stubs, documentation, or configuration from an OpenAPI 2.0 or 3.0 specification without managing the Java invocation directly.

The wrapper is not a separate code-generation engine. According to the README, it downloads an appropriate JAR file and invokes the `java` executable. That distinction matters when diagnosing failures: a problem can originate in Node.js, the downloaded generator JAR, the active Java installation, the input specification, or the selected generator. The package adds version management and configuration, but generation behavior still comes from OpenAPITools/openapi-generator.

The repository package metadata requires Node.js `>=22.0.0` for this source version. Java is a separate runtime requirement, with JDK 11 identified by the README as the minimum supported version. A Node installation alone is therefore insufficient.

How downloads, versions, and Java execution fit together

On its first invocation, the CLI selects the latest stable OpenAPI Generator version unless the project configuration specifies a different one. That selection is saved in `openapitools.json`. The README explicitly recommends committing this file because it makes later CLI calls use the recorded generator version instead of allowing an unconstrained selection.

The command name changed for version 2.x. Projects should invoke `openapi-generator-cli`, not `openapi-generator`. Version-manager subcommands provide a separate control plane for inspecting or changing selected versions:

openapi-generator-cli version-manager list

This lists versions available through the documented version manager. To select one or more version tags, the README provides this command shape:

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

The space before `<versionTags...>` is preserved from the documented form. The README does not provide concrete version tags for this example, so a specific tag should not be assumed.

The wrapper coordinates the Node process, JAR storage, and Java subprocess. It does not remove Java from the dependency chain. A machine with Node.js but no executable `java` binary on `PATH` cannot execute the generator through this package.

Installing the CLI for a local Node project

A local dependency is the README's recommended installation method because it keeps the command available through the project rather than relying on a global executable. This is also the arrangement that leads to a project-level `openapitools.json` configuration.

Install the package with npm:

npm install @openapitools/openapi-generator-cli

The README also documents Yarn as an alternative:

yarn add @openapitools/openapi-generator-cli

After installation, either invoke the executable through `npx` or add a package script. The documented `npx` entry point is:

npx openapi-generator-cli

For local use, add a script such as the following to `package.json`:

{
  "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"
  }
}

The command uses a YAML input, selects `typescript-angular`, writes to `generated-sources/openapi`, and passes generator-specific properties without spaces around the comma-separated key-value pairs. The README warns that multiple `additional-properties` values are whitespace-sensitive.

A global installation is also documented for users who want the command available outside a project:

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

After that installation, the documented executable name is `openapi-generator-cli`.

Generating from the documented Petstore specification

The first direct generation example uses the Ruby generator and a Petstore specification published in the OpenAPITools repository. On macOS and Linux, the documented command is:

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

This selects the `ruby` generator with `-g`, supplies the remote specification URL with `-i`, and directs output to `/var/tmp/ruby-client` with `-o`. Because the wrapper may need to obtain the selected JAR on its first run, Java and network availability are relevant to this example.

Windows uses the same generator and input but writes to a Windows path:

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

The differing output location is the platform-specific part of the documented example. The README does not describe automatic rollback or cleanup of a partially generated output directory if the Java process fails. Review generated files before replacing an existing client in a release workflow.

Pinning and configuring openapitools.json

After the first local execution, the CLI creates `openapitools.json` beside `package.json`. Its schema reference points at the installed package, and the `generator-cli.version` field records the OpenAPI Generator version. The README shows this as an illustrative configuration:

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

The `7.8.0` value is the version used by the README example. It should not be treated as the current stable selection after later first-run behavior has downloaded another version.

The same file can define named generator entries. Each entry can specify a generator, output pattern, input glob, and additional properties:

{
  "generator-cli": {
    "version": "7.8.0",
    "generators": {
      "v3.0": {
        "generatorName": "typescript-fetch",
        "output": "#{cwd}/output/v3.0/#{ext}/#{name}",
        "glob": "examples/v3.0/petstore.{json,yaml}"
      }
    }
  }
}

When `openapi-generator-cli generate` is called without further arguments, the README says the configuration is used automatically. Named keys such as `v3.0` can also be referenced with `--generator-key`. This turns a repeated command into a configuration-driven project operation, but it also means that changes to `openapitools.json` can change generator selection, output paths, and matching inputs without a change to the npm script.

Storage, maintenance, and license boundaries

The configuration schema includes an optional `storageDir`. The documented custom location uses `~/my/custom/storage/dir`, which places downloaded JAR files beneath a project-selected storage root. The README does not document checksum policy, proxy variables, authentication settings, or an explicit offline flag, so those behaviors should not be assumed for restricted build environments.

Maintenance is recent according to the repository status. The last push was on 2026-10-16, and releases include v2.41.0 on 2026-08-24, v2.40.1 on 2026-07-24, and v2.40.0 on 2026-07-20. These dates establish recent repository activity and release cadence, but do not by themselves guarantee compatibility with every generator or environment.

The project is licensed under Apache-2.0. That identifier covers this wrapper repository. Generated SDKs, server stubs, documentation, and other outputs may be governed by separate licenses or generator-specific notices, so teams should inspect the generated output separately. This is a licensing boundary, not legal advice.

The repository structure includes an Nx workspace with `apps/`, `libs/`, `lib/`, tests, linting, formatting, and publishing scripts. For package consumers, however, the README presents the npm installation and `openapitools.json` as the relevant interface rather than requiring development inside that workspace.

Where the CLI wrapper is the wrong fit

The clearest wrong fit is a runtime without Java. Installing the npm package does not satisfy the JAR execution requirement, and the README does not provide a pure Node implementation as an alternative.

A direct Java-based workflow is also possible in principle because OpenAPI Generator itself is a Java project. That approach avoids adding this wrapper's version manager and Node package to the invocation path, but the wrapper is the documented mechanism when a team wants npm installation and `openapitools.json` to control generator versions. The repository does not provide a direct command for the underlying JAR in this documentation, so the alternative should not be presented as a drop-in replacement command.

The CLI is also a poor fit where its configuration-driven behavior is undesirable. Running `generate` with no arguments automatically uses configured generators and glob patterns. That is convenient for a controlled project, but a workflow that expects explicit arguments every time may prefer an explicit invocation. Likewise, teams that cannot preserve generated-code review, runtime downloads, or Java subprocess output should resolve those operational constraints before adopting it.

Editorial conclusion

OpenAPI Generator CLI fits Node.js projects that want repeatable OpenAPI generation while retaining control over the underlying generator version. It is less suitable for environments without Java, teams that require an offline release process without configuring storage, or users who want to avoid a wrapper between npm and a JAR. Before adoption, verify the required Java and Node runtimes, inspect the OpenAPI Generator version written to openapitools.json, and commit that file so subsequent builds select the same generator.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. OpenAPITools/openapi-generator-cli on GitHub
4. README
5. Releases