# OpenAPI Generator: install the CLI and generate a client from your spec

> A Java-based code generator that turns an OpenAPI v2 or v3 document into client libraries, server stubs and documentation. Here is how the CLI, Maven plugin and Docker image fit together, and where the template model gets in the way.

**OpenAPITools/openapi-generator** — OpenAPI Generator allows generation of API client libraries (SDK generation), server stubs, documentation and configuration automatically given an OpenAPI Spec (v2, v3)

- Repository: https://github.com/OpenAPITools/openapi-generator
- Website: https://openapi-generator.tech
- Stars: 26,772 · Forks: 7,687
- Language: Java
- License: Apache-2.0
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/openapitools-openapi-generator

## What OpenAPI Generator does that a hand-written client cannot

The project generates API client libraries, server stubs, documentation and configuration from an OpenAPI Spec, covering v2 and v3. That is the whole product. The problem it solves is drift: an API description and the code that calls it are edited in different repositories by different people, and the description is usually the one that goes stale. Generating the client from the document makes the document the input rather than a parallel artifact.

The audience is narrower than the tagline suggests. It fits teams that already treat the OpenAPI document as an interface contract, usually because several services or several languages consume the same API. A single-language team that owns both the server and the client can often write the client by hand faster than it can tune a template. The generator pays off when the same document has to produce more than one artifact, or when the artifact has to be regenerated on every contract change.

The repository is organized as a multi-module Maven build. The modules directory holds the CLI, the Maven plugin, the Gradle plugin, the Mill plugin, an online module, a core module and the generator itself. Samples for clients, servers, documentation, schemas and OpenAPI 3 documents live under samples. That layout tells you the project is a generator engine plus several front ends, not a single binary.

## How the generator turns a document into code

The pipeline is: parse the OpenAPI document into an internal model, apply a generator for the target language, then run that generator's templates to emit files. The language-specific behavior lives in the generator classes, and the output shape lives in the template files. Options passed on the command line, in a config file, or through the Maven plugin influence both stages.

This split is the part worth understanding before adopting it. When the generated client does not match your conventions, you are not editing code, you are editing templates or generator options. That is a different skill from writing the client by hand, and it is the main ongoing cost of the tool. The project ships a samples directory with generated output for many targets, which is the practical way to see what a given generator emits before you commit to it.

The README carries an explicit warning that if the OpenAPI spec, templates or any input such as options or environment variables come from an untrusted source or environment, those inputs should be reviewed before generating, to avoid security issues such as code injection. Treat that as a design property, not boilerplate: the templates are code, and a template from an untrusted source is untrusted code. The same section directs security reports to team@openapitools.org.

One naming point that trips people up: the README states that both OpenAPI Tools and OpenAPI Generator are not affiliated with the OpenAPI Initiative.

## Installing the CLI and generating your first client

The project publishes to Maven Central under the group org.openapitools, and the README links the stable release badge to that metadata. The CLI module is what most people mean by "openapi-generator install". The repository also ships a Dockerfile based on maven:3-eclipse-temurin-17 that builds the generator inside the image, and a run-in-docker.sh script at the top level.

The README does not spell out an npm install path for the CLI in the text captured here, so do not assume one. If you want the command-line tool, take it from the published artifact or from the Docker image rather than guessing a package name.

The Dockerfile shows how the project builds itself. It sets a working directory, copies the module poms, and takes Maven offline before copying sources:

```dockerfile
FROM maven:3-eclipse-temurin-17

ENV GEN_DIR /opt/openapi-generator
WORKDIR ${GEN_DIR}
VOLUME  ${MAVEN_HOME}/.m2/repository

COPY ./pom.xml ${GEN_DIR}
RUN mvn dependency:go-offline
```

The comment in the Dockerfile explains the ordering: all poms are copied, then the build goes offline, so that code changes can be cached without fetching every dependency again. That is the same reason to wrap generation in a container rather than installing the toolchain on every machine.

For a Java build, the Maven plugin is the more common route, and it lives in modules/openapi-generator-maven-plugin. The repository keeps the plugin's pom alongside the others, and the README's related material points at it directly. A team that already builds with Maven gets regeneration as part of the normal build rather than as a separate manual step.

If you would rather not install Java tooling at all, run-in-docker.sh at the top level wraps the container build for local use. The docker-compose.yml in the repository is for the documentation site, not for the generator: it builds a docusaurus service on ports 3000 and 35729 from the docs and website directories. Do not confuse the two when you are looking for a container to run generation in.

## Where the template model works against you

The generated code is only as good as the document it came from. If your spec is hand-written and never validated, the generator will faithfully emit a client for an API that does not exist in that shape. There is no reconciliation step; the tool is a compiler, not a contract checker.

Customization is the second edge. Changing a naming convention, an HTTP client, or a serialization library means either finding an option that already exists or maintaining a template fork. Once you fork templates, upstream releases become a merge exercise, and the project ships releases regularly: v7.25.0 on 2026-08-24, v7.24.0 on 2026-07-20, v7.23.0 on 2026-06-08, with master carrying 7.26.0. A team that cannot absorb that cadence should pin a version and upgrade deliberately rather than tracking master.

There is also a real trust boundary. The README's warning about untrusted specs, templates, options and environment variables is the clearest statement available about failure modes, and it points at code injection. If your generation step runs in CI on pull requests from forks, that warning is directly relevant to how you wire the job.

Finally, the tool is the wrong choice when the API surface is small and stable. Generating a client for four endpoints and then maintaining templates for it costs more than writing those four calls.

## OpenAPI Generator compared with Swagger Codegen and other generators

The README links a migration guide from Swagger Codegen, which is the comparison most people arrive with. The two share lineage, and the repository carries docs/migration-from-swagger-codegen.md for teams moving across. The practical difference visible here is not a feature list but the release and maintenance picture: OpenAPI Generator publishes dated releases and keeps a multi-module build with CLI, Maven, Gradle and Mill front ends.

Against nswag, orval and kiota, the distinction is scope. Those tools target particular ecosystems, and the search data shows people comparing them directly. OpenAPI Generator's approach is breadth: one engine, many language generators, one document. If you need a TypeScript client tuned to one fetch library, a narrower generator may fit better, because it has fewer knobs and less template surface to learn. If you need Java, Python, Rust and Flutter clients from the same document, breadth is the reason to pick this one.

The honest framing is that OpenAPI Generator optimizes for coverage and configurability, and pays for it in per-language polish. Expect to inspect the generated output for your target before you build on it.

## Maintenance, upgrades and the Apache-2.0 licence

The repository is not archived. Its last push was on 2026-09-20, one day before the release line above, so the project is under current development by any reasonable reading of that date. Releases are monthly-ish: three dated releases between June and August 2026.

Upgrade cost depends entirely on whether you forked templates. With stock templates, an upgrade is a version bump plus a regeneration and a diff of the output. With forked templates, it is a merge against template files that upstream may have changed, and the diff of generated output becomes noise that hides the real template conflicts. The samples directory is useful here: comparing upstream sample output between two versions shows what actually changed in the emitted code.

The licence is Apache-2.0, and the Dockerfile copies ./LICENSE into the image with the comment that it is required from a licensing standpoint. Generated code inherits whatever the generator's templates carry, and the project does not present itself as giving legal advice on that. If you redistribute generated clients, read the licence and the generated file headers rather than assuming the Apache-2.0 grant covers every emitted artifact identically.

## Conclusion

Adopt OpenAPI Generator when one OpenAPI document must produce clients or server stubs in several languages and you can pin the generator version in CI. Do not adopt it if you want a hand-shaped client for a single language, or if your spec is written by hand and never validated, because the generator reproduces whatever the document says. Before committing, run a generation against your own spec, then diff the generated output against your repository and check whether the default templates for your language match your HTTP client and serialization choices. If they do not, the cost is in custom templates, not in the generator itself.

## FAQ

### What does OpenAPI Generator do?

It generates API client libraries, server stubs, documentation and configuration from an OpenAPI Spec covering v2 and v3. You point it at a document and a target language, and it emits a project for that language.

### How do I install openapi-generator-cli?

The project publishes artifacts to Maven Central under the org.openapitools group, and the repository also ships a Dockerfile based on maven:3-eclipse-temurin-17 plus a run-in-docker.sh script. The README does not document an npm install path for the CLI.

### How do I use the OpenAPI Generator Maven plugin?

Add the openapi-generator-maven-plugin to your build, bind its generate goal, and set the input spec and generator name in the configuration. The generated sources are then written into the project during the build.

### What is the OpenAPI Generator CLI?

It is the command-line front end to the generator, living in the modules/openapi-generator-cli module alongside the Maven, Gradle and Mill plugins. It takes an input spec, a generator name and an output directory.

### How does OpenAPI Generator differ from Swagger Codegen?

The README links a migration guide at docs/migration-from-swagger-codegen.md for teams moving from Swagger Codegen. The available documentation does not enumerate the feature differences, so the migration guide is the source to read.

### What is the OpenAPI Generator Maven plugin?

It is the Maven front end to the same generator engine, kept in the modules/openapi-generator-maven-plugin directory. It lets a Java build regenerate sources as part of the normal lifecycle instead of running a separate command.

## Sources

- [License: Apache-2.0](https://github.com/OpenAPITools/openapi-generator/blob/master/LICENSE)
- [OpenAPITools/openapi-generator on GitHub](https://github.com/OpenAPITools/openapi-generator)
- [Project website](https://openapi-generator.tech)
- [README](https://github.com/OpenAPITools/openapi-generator/blob/master/README.md)
- [Releases](https://github.com/OpenAPITools/openapi-generator/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/openapitools-openapi-generator