Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 37 ยท Code Generation

OpenAPI Generator on the Command Line

Learn the openapi-generator-cli commands, config files, additional properties, custom templates and the ignore file, with runnable stand-ins for the file logic.

OpenAPI Generator is the most widely used open-source generator. It ships hundreds of generators for clients, servers, documentation and config files, and runs as a Java program. You rarely call the JAR directly. Instead you use one of three wrappers: the npm package @openapitools/openapi-generator-cli, the Docker image openapitools/openapi-generator-cli, or Homebrew.

The tool itself cannot run on this website, so the commands below are read-only. Two small Python stand-ins show how the config and ignore files behave. Everything else is described as it works in the real tool.

Install and discover

Terminal
# npm wrapper (downloads the JAR on first use, needs Java)
npm install --save-dev @openapitools/openapi-generator-cli

# or Docker, no local Java needed
docker run --rm -v "$PWD:/local" openapitools/openapi-generator-cli version

# list every generator name (python, typescript-fetch, spring, go, ...)
npx openapi-generator-cli list

# show the options of one generator
npx openapi-generator-cli config-help -g python

Generators are grouped by kind: CLIENT, SERVER, DOCUMENTATION, CONFIG. The name after -g picks the template set.

The generate command

The command you will use most:

Terminal
npx openapi-generator-cli generate \
  -i openapi.yaml \
  -g python \
  -o ./clients/python \
  --additional-properties=packageName=bookstore_client,projectName=bookstore-client
Flag Meaning
-i Input spec: a local path or an HTTP URL
-g Generator name
-o Output directory
-c A JSON or YAML config file with generator options
-t A directory of custom templates that override the built-in ones
--additional-properties Comma-separated key=value generator options
--global-property Limit what is generated, e.g. models,apis,supportingFiles
--skip-validate-spec Do not stop on spec warnings (use sparingly)

You can check a spec before generating:

Terminal
npx openapi-generator-cli validate -i openapi.yaml

Config files instead of long commands

Long option lists belong in a file that lives in git next to the spec. A config file for the Python generator:

YAML
# python-config.yaml
packageName: bookstore_client
projectName: bookstore-client
packageVersion: 1.0.0
library: urllib3
Terminal
npx openapi-generator-cli generate -i openapi.yaml -g python -o ./clients/python -c python-config.yaml

If you use the npm wrapper, a single openapitools.json file can hold several named generators and run them all with npx openapi-generator-cli generate. Each generator lists its own input and options.

What the output folder contains

After a run, the output folder holds the generated sources plus two bookkeeping items:

  • .openapi-generator/FILES lists every file the run produced, so tools can clean up stale ones.
  • .openapi-generator-ignore is a file you write. It uses .gitignore-style patterns to protect files from being overwritten. The first generation creates the file with a few comments; later runs skip any path that matches.
Python Stand-in: how an ignore file protects hand-written files

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The stand-in uses simple shell-style matching. The real file supports the full .gitignore syntax, including ** and ! negation, but the idea is the same: protected paths survive regeneration.

Merging options in the right order

Options can come from several places. When they disagree, the more specific source wins. The stand-in below applies the order used in practice: generator defaults, then the config file, then --additional-properties on the command line.

Python Stand-in: option precedence

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Custom templates

Generators render text through Mustache templates. To change the output style, copy the template you want to change into your own folder and pass it with -t. Find the original templates in the project's modules/openapi-generator/src/main/resources/<generator>/ directory. Keep your folder small: only the files you changed, since the tool falls back to the built-in template for everything else.

Template variables and file names change between major releases. After upgrading the generator, regenerate and read the diff before you trust the new output. Pin the version in openapitools.json or in your Docker tag so CI is repeatable.

A sensible CI recipe

  1. Keep the spec, config file and ignore file in git.
  2. Pin the generator version.
  3. Run the generator in CI and fail the build if the committed output differs from a fresh run (a "no drift" check).
  4. Publish the generated package from CI, never from a laptop.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. Which flag selects the template set, for example python or typescript-fetch?

    -g names the generator. -i is the input spec, -o the output directory and -t a custom template folder.
  2. 2. What does .openapi-generator-ignore do?

    It uses gitignore-style patterns; matching paths are left alone when you regenerate.
  3. 3. A config file sets packageVersion to 2.1.0 and the command line sets it to 2.1.1. Which value is used?

    Command-line additional properties override the config file, which overrides defaults.

Summary

  • Use the npm wrapper or Docker image of OpenAPI Generator; list and config-help show generators and options.
  • generate -i spec -g name -o dir is the core command; -c reads options from a file.
  • .openapi-generator-ignore protects hand-written files; custom Mustache templates change the style.
  • Pin the version and check for drift in CI.
  • The Python snippets here are stand-ins for the file logic, not the generator.

Next: Generating server stubs