Pin the generator to one exact release in every place it runs: the npm wrapper, the Docker image, the JAR URL or the Maven and Gradle plugin version. Then regenerate only when you choose to bump that version. An unpinned generator can change your client code with no change to your spec.
Why the version matters
A generator is a program that turns your OpenAPI file into source code. The output depends on two inputs: the spec and the generator version, including its built in templates. Change either and the code changes.
If CI installs "latest" each run, a new generator release can alter generated files, imports and dependency declarations while your spec stays untouched. Your diff then mixes real API changes with tooling changes, and nobody can say which is which.
Pin it for each install method
The project documents several ways to install the CLI. Each has its own way to hold a version.
| Method | How to pin |
|---|---|
| npm wrapper | Use the version manager command to set an exact release, or install it as a dev dependency so your lockfile records it |
| JAR | Put the exact version in the Maven Central download URL |
| Bash launcher script | Set the OPENAPI_GENERATOR_VERSION environment variable |
| Docker | Use a specific image tag, and a digest if you want it immutable |
| Maven or Gradle plugin | Set the plugin version explicitly in the build file |
The npm wrapper documentation shows the form below. Replace the version with the one you have tested.
npm install @openapitools/openapi-generator-cli -D
npx openapi-generator-cli version-manager set 7.26.0
For the Maven plugin the documentation example sets the version in the plugin block, which is the right place to hold it.
A short procedure
- Pick the current stable release and record it in one file, such as a tool versions file or the build file.
- Make every CI job and every developer machine read that one value.
- Add a check that fails if the reported generator version differs from the recorded one. The CLI has a version command for this.
- Generate, commit the output, and review the diff.
- Bump the version in its own pull request, regenerate, and review that diff separately from any spec change.
Step 5 is the habit that pays off. When the only change is the tool version, every line of the diff is attributable to the tool.
What pinning does not cover
Pinning the generator does not pin what the generator emits. The generated project still declares dependencies such as an HTTP library, and those need their own lockfile or version constraints. See what a lockfile stops and what it cannot for the limits, and dependency risk in generated clients for what ends up in the output.
Pinning also does not verify the download itself. If you can, fetch the artifact through your own registry or mirror so the bytes are the ones you reviewed.
Where Safeguard fits
Safeguard does SBOM and dependency scanning on the repository that holds your generated client, so the libraries the generator chose show up in the inventory next to everything else. You can try it with the free scan at gold.safeguard.sh/scan.
Try it yourself
Click through it at your own pace, or open it full screen. Look for how direct and transitive dependencies are listed together, which is how a generated client appears too.
Quick check
Is pinning the generator the same as committing a lockfile?
No. A lockfile pins the libraries your project installs. Pinning the generator pins the tool that writes the code. You usually want both.
Can I rely on the latest tag of the Docker image?
It is convenient, but it moves. For repeatable output, use a specific tag or a digest.
Sources
Last reviewed: 19 October 2026.
