OpenAPI Generator: The 2026 Practical Usage Guide

If you have a working OpenAPI spec and you are still hand-writing client SDKs for every language your customers ask for, you are doing the slow version. OpenAPI Generator is the tool that takes a .yaml or .json spec and emits a typed client, a server stub, or even reference docs in over 50 target languages and frameworks. It is the open-source successor to Swagger Codegen, the project most teams already know about but never quite get around to setting up. If you want a refresher on writing the spec itself first, our OpenAPI documentation guide covers the schema side end to end.

This is a usage guide, not a marketing page. We will walk through what OpenAPI Generator actually does, how to install it three different ways, how to generate your first TypeScript and Python clients, how to customize templates without forking the project, and how it differs from Swagger Codegen and from rendering tools like Redoc. The goal is that by the end you can run a single command, hand a typed SDK to a frontend engineer, and stop maintaining HTTP wrapper code by hand.

The OpenAPI Generator project on GitHub has 26.2k stars and shipped its 7.22.0 release on April 28, 2026, which is a useful proxy for how much momentum the tool has compared to its predecessor (OpenAPITools/openapi-generator, 2026). With Postman's 2025 State of the API report finding that 82% of organizations now have some level of an API-first practice (Postman, 2025), the bottleneck for most teams has shifted from writing the spec to actually using it. That is the gap OpenAPI Generator fills.

What is OpenAPI Generator?

OpenAPI Generator is an open-source CLI and library that reads an OpenAPI 2.0 or 3.x specification and produces working code from it. Given a petstore.yaml, you can ask it to emit a TypeScript axios client, a Python requests SDK, a Spring Boot server stub, a Go Gin server, an Android Retrofit client, or static HTML reference documentation. The same input file feeds every output.

The project is governed by the OpenAPI Tools community on GitHub. It is a hard fork of Swagger Codegen, created in May 2018 after a group of the most active maintainers split off to escape what they called "decision-making chaos" inside the original project. The fork shipped community governance, faster releases, and broader generator coverage from day one, and it is now the more active of the two by a wide margin.

You give the generator three things: a spec file, a generator name (like typescript-axios or python or spring), and an output directory. It writes the resulting project to disk. From there you build it like any other library, publish it to npm or PyPI, and your API consumers install a typed package instead of hitting fetch themselves.

Why use a code generator instead of writing clients by hand?

The honest answer is consistency at scale. One language is fine to maintain manually. Six languages plus a server stub plus mock servers is not. Every time you add an endpoint, change a parameter, or rename a field, you have to update every hand-rolled client and hope nobody missed a spot.

A generated client gets the change for free. You update the spec, regenerate, publish a new SDK version, and every consumer pulls the typed update. The compiler catches drift. CI catches drift. Customer support does not catch drift, because there is none.

Three concrete benefits show up in real codebases:

1. No more HTTP boilerplate. Generated clients ship with retry logic, auth handling, serialization, and error types out of the box. You write business logic, not URL strings.
2. Type safety across the wire. A TypeScript client generated from your spec gives you autocomplete on every parameter and return value. Wrong field name? Compile error. Wrong status code branch? Compile error.
3. Server stubs that match the contract. When you generate the server side from the same spec, the request shape, response shape, and validation are guaranteed to match what the spec promises. Contract drift becomes a compile error instead of a 3am incident.

For teams shipping public APIs, this is also how you get to the SDK documentation story without hiring a full-time SDK engineer. The generator does the work; you ship the docs around it.

How do you install OpenAPI Generator?

There are three supported install paths and they all run the same generators with the same options. Pick whichever fits your stack.

Docker (works anywhere)

The Docker image is the simplest option if you do not want Java or Node on the box. Pull the image and run it against a spec mounted as a volume:

docker run --rm \
  -v ${PWD}:/local \
  openapitools/openapi-generator-cli generate \
  -i /local/petstore.yaml \
  -g typescript-axios \
  -o /local/sdk-ts

Useful in CI, in containers, and on developer machines where you do not want to manage a JDK. The image is updated on every release.

npm (@openapitools/openapi-generator-cli)

For Node-based teams, the npm wrapper is the most ergonomic install. It downloads the right Java JAR behind the scenes and pins the version in your package.json:

npm install @openapitools/openapi-generator-cli --save-dev
npx openapi-generator-cli version
npx openapi-generator-cli generate \
  -i ./petstore.yaml \
  -g typescript-axios \
  -o ./sdk-ts

This is the install path most JavaScript and TypeScript projects use because the version is reproducible across the team. Note that even though it is an npm package, it still requires a JRE on the machine.

Maven, Gradle, or Homebrew

If you live in the JVM world, the Maven plugin is the standard choice and runs as part of your build:

<plugin>
  <groupId>org.openapitools</groupId>
  <artifactId>openapi-generator-maven-plugin</artifactId>
  <version>7.22.0</version>
  <executions>
    <execution>
      <goals><goal>generate</goal></goals>
      <configuration>
        <inputSpec>${project.basedir}/src/main/resources/petstore.yaml</inputSpec>
        <generatorName>spring</generatorName>
        <apiPackage>com.example.api</apiPackage>
        <modelPackage>com.example.model</modelPackage>
      </configuration>
    </execution>
  </executions>
</plugin>

On macOS, brew install openapi-generator gets you the CLI directly. The official installation page covers Gradle, Bazel, and the standalone JAR.

How do you generate your first client?

The minimum command is three flags: input spec, generator name, output directory. Here is a TypeScript axios client generated from the canonical petstore spec:

npx openapi-generator-cli generate \
  -i https://petstore3.swagger.io/api/v3/openapi.json \
  -g typescript-axios \
  -o ./pet-client

That command writes a complete TypeScript project to ./pet-client with a package.json, tsconfig.json, and a class per tag in the spec. Inside, you get fully typed PetApi, StoreApi, and UserApi classes with methods that mirror your operations. Calling petApi.findPetsByStatus("available") returns a typed Pet[].

Swap the -g flag for any of the 50+ supported generators and the same spec produces a different client. -g python gives you a Pydantic-modeled Python client. -g go gives you a Go module. -g java gives you a Java client with OkHttp underneath. Same spec, different output.

For server-side code, the pattern is identical:

npx openapi-generator-cli generate \
  -i ./petstore.yaml \
  -g spring \
  -o ./pet-server-spring

You get a Spring Boot project with controllers, request DTOs, response DTOs, and validation annotations wired up. Implementing the actual business logic is your job; everything else is generated.

Which generator should you pick?

The -g flag is the single most important choice. The wrong generator means fighting the tool for a week before you switch. Here is the rough mapping that holds for most SaaS teams in 2026.

If you are picking the typescript client and unsure between axios and fetch, default to typescript-axios for browser code (better error handling) and typescript-fetch if you need to ship to edge runtimes that lack axios support. The full list of generators is at openapi-generator.tech/docs/generators. Run npx openapi-generator-cli list to see them in your installed version.

How do you customize the generated code?

Out-of-the-box defaults are good but rarely perfect. There are three layers of customization, each more invasive than the last.

1. Config options (no code, JSON or CLI flags)

Most generators expose dozens of options. For the TypeScript axios generator, you can change the package name, npm version, supported HTTP types, and dozens of formatting choices through a config file:

{
  "npmName": "@yourcompany/api-client",
  "npmVersion": "1.0.0",
  "supportsES6": true,
  "withSeparateModelsAndApi": true,
  "modelPackage": "models",
  "apiPackage": "apis"
}

Pass it with -c config.json. List all options for a generator with npx openapi-generator-cli config-help -g typescript-axios. This is where 80% of teams stop, and it is enough.

2. Custom Mustache templates

Each generator ships with Mustache templates that produce its output files. You can override any of them by exporting the originals, editing them, and pointing the generator at your override directory:

npx openapi-generator-cli author template \
  -g typescript-axios \
  -o ./custom-templates

# edit ./custom-templates/api.mustache, then:
npx openapi-generator-cli generate \
  -i petstore.yaml \
  -g typescript-axios \
  -o ./client \
  -t ./custom-templates

This is how you change the shape of the generated Api class without forking the project. Useful when your team has a house style for retries, logging, or error wrapping.

3. Custom generator (Java plugin)

If you need wholesale changes (a new target language, a different file layout) you write a Java class that extends one of the existing generator base classes and ship it as a JAR. This is what the Travelport team in Lukas Niedoba's well-known case study did for a custom C++ target. The lesson from that story is worth keeping in mind: a custom generator is a real maintenance burden as your spec evolves. Try templates first.

OpenAPI Generator vs Swagger Codegen

The two tools share most of their lineage and a lot of their generators, but they diverge sharply on activity and governance.

If you are starting fresh in 2026, pick OpenAPI Generator. The active maintainer base is bigger, the release cadence is faster, and the generators for newer languages (Rust, Swift 6, Kotlin Multiplatform) are better. The only reason to stay on Swagger Codegen today is that you have an existing build using it and the migration is not worth the disruption. For a deeper take on the naming history, see our Swagger vs OpenAPI explainer.

Where does OpenAPI Generator fit in your docs stack?

OpenAPI Generator handles the machine-readable side of your API surface: SDKs your customers install, server stubs your engineers build on, mock servers your QA team hits. It does not handle human-facing docs.

For the human side, you still need a docs site that hosts guides, tutorials, and a polished reference. That is where renderers like Redoc come in for the spec view, and where a full docs platform comes in for everything around it. For teams shipping a SaaS product where the API is one part of the offering and not the whole product, Docsio generates the rest of the documentation site (tutorials, getting-started guides, conceptual docs) directly from your existing site, branded automatically. The pairing is straightforward: OpenAPI Generator emits the SDKs, Docsio publishes the docs site around them, and you ship both without hiring an SDK engineer or a technical writer.

For pure reference rendering, look at our API reference documentation guide. For the broader picture of how to structure docs around a generated SDK, SDK documentation strategy covers it.

Common pitfalls and how to avoid them

A few things bite almost every team the first time. Knowing them ahead saves a week.

Forgetting to lock the version. OpenAPI Generator releases monthly. If your CI runs latest, your generated code will silently change between builds. Pin the version in package.json, pom.xml, or your Docker tag.

Trying to commit generated code to git. Most teams check in only the spec and the build config, then regenerate at build time. Committing the output makes review noisy and merge conflicts ugly. Treat the SDK as a build artifact, not a source file.

Choosing the wrong server generator. spring and kotlin-spring look similar but produce different code. Check the generator docs before you commit; switching mid-project is painful.

Ignoring additionalProperties and discriminators. If your spec uses oneOf with discriminators or open additionalProperties, the generator's behavior varies by language. Test deserialization before you ship.

Versioning the spec, not the SDK. When you change the spec, bump the SDK version too. Otherwise consumers think the same client version means the same API surface, and that breaks trust. We covered this pattern in API versioning.

Frequently Asked Questions

What does an OpenAPI generator do?

An OpenAPI generator reads an OpenAPI specification (a YAML or JSON file describing an API) and produces working code from it. That code can be a client SDK in any of 50+ supported languages, a server stub for frameworks like Spring or FastAPI, static HTML reference documentation, or configuration for tools like Postman. One spec, many outputs.

Does OpenAPI Generator require Java?

Yes, the generator runs on the JVM and requires a Java Runtime Environment, even when you install it via npm or Homebrew. The Docker image is the only install path that does not require Java on the host machine, because the JRE ships inside the container. For most teams the JVM dependency is invisible after install.

Is OpenAPI Generator the same as Swagger Codegen?

No. OpenAPI Generator was forked from Swagger Codegen in May 2018 by a group of the most active maintainers and is now a separate, faster-moving project. They share a lot of the same generators but OpenAPI Generator releases more often, supports more languages, and is community-governed rather than vendor-led.

What is the difference between OpenAPI Generator and Redoc?

They solve different problems. OpenAPI Generator produces code (SDKs, server stubs, configurations) from a spec. Redoc produces an interactive HTML reference site from a spec. You usually want both: OpenAPI Generator to ship clients to customers, and a renderer like Redoc or a full docs platform to publish the human-readable reference.

Can I use OpenAPI Generator without writing the spec by hand?

Yes. Frameworks like FastAPI, NestJS, and Spring with springdoc-openapi generate the OpenAPI spec automatically from your code. You point OpenAPI Generator at the resulting openapi.json and produce clients from there. The full loop is code-first on the server, generated SDKs on the client, no hand-written contracts in between.

Ship the SDK, ship the docs

OpenAPI Generator is the reason most modern API teams stop hand-writing clients. One spec, fifty languages, monthly releases, and a healthy community behind it. The install takes five minutes, the first client generation takes one command, and the long-term payoff is that your SDKs never drift from your contract.

For the human-facing docs around that SDK (tutorials, getting-started guides, branded reference site) the same speed-up applies. Docsio generates a complete documentation site from your URL in under five minutes, branded automatically, with one-click publishing. Pair it with OpenAPI Generator and you have machine clients plus human docs without hiring either an SDK engineer or a docs team. See pricing for both plans.