DEV Community

Cover image for OpenAPI Generator: How to Generate API Client and Server Code
Hassann
Hassann

Posted on • Originally published at apidog.com

OpenAPI Generator: How to Generate API Client and Server Code

OpenAPI Generator is an open-source CLI that turns an OpenAPI or Swagger spec into working code: client SDKs, server stubs, docs, and configuration files. In practice, you install the CLI, point it at openapi.yaml, choose a generator such as typescript-axios or spring, and write the generated output to a target folder.

Try Apidog today

What OpenAPI Generator does

OpenAPI Generator reads a machine-readable API contract and generates source code from it.

Given an openapi.yaml or openapi.json file, it can generate:

  • Client SDKs for calling an API
  • Server stubs for implementing an API
  • API documentation
  • Configuration files and supporting project files

It supports both OpenAPI v2, also known as Swagger, and OpenAPI v3. The project is maintained by the OpenAPITools organization and includes templates for many languages and frameworks.

The important distinction: OpenAPI Generator is primarily a code generator, not a documentation renderer. Tools like Swagger UI and Redoc turn a spec into human-readable HTML docs. OpenAPI Generator produces code you can compile, package, and ship.

OpenAPI Generator vs Swagger Codegen

If you have used Swagger Codegen, OpenAPI Generator will feel familiar.

OpenAPI Generator was forked from Swagger Codegen in May 2018, between Swagger Codegen versions 2.3.1 and 2.4.0, by more than 40 contributors and template creators.

The fork happened after disagreement over the direction of Swagger Codegen 3.0.0. The OpenAPI Generator community wanted a faster, more open release cycle. If you are comparing the two tools, this Swagger Codegen alternatives breakdown covers the practical differences.

Install OpenAPI Generator

You have several installation options. Choose the one that fits your environment.

Option 1: npm

For most JavaScript and TypeScript projects, the npm wrapper is the simplest option. It downloads and manages the underlying JAR for you.

npm install @openapitools/openapi-generator-cli -g
Enter fullscreen mode Exit fullscreen mode

Verify the install:

openapi-generator-cli version
Enter fullscreen mode Exit fullscreen mode

You can also run it without installing globally:

npx @openapitools/openapi-generator-cli version
Enter fullscreen mode Exit fullscreen mode

Option 2: Homebrew on macOS 

brew install openapi-generator
Enter fullscreen mode Exit fullscreen mode

Then verify:

openapi-generator version
Enter fullscreen mode Exit fullscreen mode

Option 3: Standalone JAR

OpenAPI Generator is a Java application. If you want to avoid npm or Homebrew, download the JAR directly from Maven Central and run it with Java.

wget https://repo1.maven.org/maven2/org/openapitools/openapi-generator-cli/7.23.0/openapi-generator-cli-7.23.0.jar -O openapi-generator-cli.jar

java -jar openapi-generator-cli.jar help
Enter fullscreen mode Exit fullscreen mode

Check Maven Central for the latest version before downloading.

Option 4: Docker

Use Docker if you do not want to install Java or Node.js locally.

docker pull openapitools/openapi-generator-cli
Enter fullscreen mode Exit fullscreen mode

Run the generator by mounting your current working directory into the container:

docker run --rm -v "${PWD}:/local" openapitools/openapi-generator-cli generate \
  -i /local/openapi.yaml \
  -g go \
  -o /local/out/go
Enter fullscreen mode Exit fullscreen mode

List available generators

Before generating code, inspect the available generators.

openapi-generator-cli list
Enter fullscreen mode Exit fullscreen mode

For a compact one-generator-per-line view:

openapi-generator-cli list -s | tr ',' '\n'
Enter fullscreen mode Exit fullscreen mode

The list is grouped by generator type:

  • Client generators, such as typescript-axios, java, python, and go
  • Server generators, such as spring
  • Documentation generators
  • Schema generators

Generate a client SDK

The main command is generate.

You will usually pass these three flags:

  • -i, --input-spec: path or URL to your OpenAPI spec
  • -g, --generator-name: generator to use
  • -o, --output: output directory

Generate a TypeScript client that uses Axios:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client
Enter fullscreen mode Exit fullscreen mode

This writes a typed client into ./client.

In the generated SDK:

  • Operations become callable methods
  • Schemas become typed models
  • Request and response shapes come from the OpenAPI contract

Generate SDKs for other languages by changing the generator name and output directory:

openapi-generator-cli generate -i openapi.yaml -g java   -o ./client-java
openapi-generator-cli generate -i openapi.yaml -g python -o ./client-python
openapi-generator-cli generate -i openapi.yaml -g go     -o ./client-go
Enter fullscreen mode Exit fullscreen mode

Because all SDKs come from the same spec, they stay aligned with the same API contract. When the spec changes, regenerate the clients.

Generate server stubs

Server generators work in the opposite direction. Instead of code that calls your API, they create a scaffold for implementing it.

A generated server stub can include:

  • Routing
  • Controllers
  • Request models
  • Response models
  • Handler interfaces

For example, generate a Spring Boot server stub:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g spring \
  -o ./server-spring
Enter fullscreen mode Exit fullscreen mode

The generated project gives you controllers and DTOs based on your spec. You then implement the business logic inside the generated interfaces or handler methods.

This keeps the running API aligned with the published OpenAPI contract.

Configure generated output

The default output is rarely exactly what a production project needs. OpenAPI Generator gives you several ways to control the result.

Use additional properties

Most generators expose language-specific options through --additional-properties, also available as -p.

Pass options as comma-separated key=value pairs:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client \
  --additional-properties=npmName=@acme/api-client,supportsES6=true,withSeparateModelsAndApi=true
Enter fullscreen mode Exit fullscreen mode

Each generator supports different properties, so check the documentation for the generator you are using.

Use a config file

If the command becomes too long, move the settings into a config file.

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client \
  -c config.yaml
Enter fullscreen mode Exit fullscreen mode

A config file keeps generation settings versioned next to your spec.

Example:

npmName: "@acme/api-client"
supportsES6: true
withSeparateModelsAndApi: true
Enter fullscreen mode Exit fullscreen mode

This makes local and CI generation more reproducible.

Ignore files you do not want overwritten

OpenAPI Generator reads a .openapi-generator-ignore file from the output directory. It uses syntax similar to .gitignore.

Use it to prevent generated runs from overwriting files you maintain manually.

# .openapi-generator-ignore
*.md
src/custom/**
Enter fullscreen mode Exit fullscreen mode

You can also point to an ignore file in another location:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client \
  --ignore-file-override ./openapi-generator-ignore
Enter fullscreen mode Exit fullscreen mode

Customize templates

OpenAPI Generator uses Mustache templates. If the default output does not match your project style, copy and customize the templates, then pass your template directory with -t.

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client \
  -t ./my-templates
Enter fullscreen mode Exit fullscreen mode

Custom templates are useful when you need:

  • A standard file header
  • Different naming conventions
  • A custom HTTP client wrapper
  • In-house code structure across every generated SDK

Run OpenAPI Generator in CI

Code generation should run in your pipeline, not only on one developer’s machine.

For example, generate a TypeScript client in GitHub Actions with npx:

- name: Generate API client
  run: npx @openapitools/openapi-generator-cli generate -i openapi.yaml -g typescript-axios -o ./client
Enter fullscreen mode Exit fullscreen mode

A common CI pattern is:

  1. Check out the repo.
  2. Install dependencies.
  3. Regenerate the SDK from openapi.yaml.
  4. Fail the build if generated files differ from committed files.

That catches cases where the OpenAPI spec changed but the SDK was not regenerated.

Keep the OpenAPI spec as the source of truth

OpenAPI Generator is only as good as the spec you give it.

If the contract is vague, incomplete, or invalid, the generated SDK or server stub will reflect those problems. The best workflow is to validate the spec before generation.

This is where Apidog fits. Apidog is an OpenAPI-native API platform where your design work and OpenAPI document stay connected. You can design or import the API, then use the OpenAPI document as the source of truth for generation, testing, and collaboration.

A practical workflow looks like this:

  1. Design or import the OpenAPI spec in Apidog. Branch support lets you work on changes in isolation, similar to version-controlling OpenAPI with Git.
  2. Validate and lint the spec before generation. A spec that passes an OpenAPI linter and a Swagger validator usually produces cleaner generated code.
  3. Export the validated spec.
  4. Run OpenAPI Generator to create SDKs or server stubs.

You can also keep the spec synced with your repo by syncing the OpenAPI spec to GitHub, then review API contract changes with an OpenAPI diff before they ship.

If you are moving from older tooling, this Swagger alternatives for API design and testing comparison is a useful starting point.

Where Apidog stops and OpenAPI Generator starts

Apidog and OpenAPI Generator solve different parts of the workflow.

Apidog does not generate full client SDKs or server stubs. OpenAPI Generator does that.

Apidog provides ready-to-copy client request snippets for individual endpoints in many languages and HTTP clients. These are useful for scripts and examples, but they are not packaged SDKs.

For a generated, versioned client library or server scaffold, export the OpenAPI spec from Apidog and run OpenAPI Generator.

Apidog also provides its own command-line test runner, the Apidog CLI. It is separate from OpenAPI Generator and is used for running API tests in CI, not for SDK generation.

Install it with npm:

npm install -g apidog-cli@latest
Enter fullscreen mode Exit fullscreen mode

Run an API test scenario:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t <testScenarioId> \
  -e <envId> \
  -r cli,html \
  -n 1
Enter fullscreen mode Exit fullscreen mode

The flags mean:

  • --access-token: authentication token
  • -t: test scenario ID
  • -e: environment ID
  • -r: reporters to generate
  • -n: number of iterations

Run it on a current Node.js LTS release. For setup details, see the Apidog CLI installation guide and this walkthrough on testing a REST API from the command line.

The full loop is:

  1. Design and validate the OpenAPI spec in Apidog.
  2. Generate SDKs and server stubs with OpenAPI Generator.
  3. Test the running API with the Apidog CLI.

Try Apidog free, no credit card required.

Frequently Asked Questions

What is OpenAPI Generator?

OpenAPI Generator is an open-source tool from the OpenAPITools organization. It generates code from an OpenAPI or Swagger spec, including client SDKs, server stubs, documentation, and configuration files. It supports OpenAPI v2 and OpenAPI v3.

How do you use OpenAPI Generator?

Install the CLI, then run generate with your spec, generator name, and output folder.

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

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client
Enter fullscreen mode Exit fullscreen mode

Run this first to see available generators:

openapi-generator-cli list
Enter fullscreen mode Exit fullscreen mode

How does OpenAPI Generator work?

OpenAPI Generator parses your OpenAPI spec into an internal model, then renders that model through Mustache templates for the selected generator.

Typically:

  • Each API operation becomes a method or handler
  • Each schema becomes a typed model
  • Generator templates define the final code structure

You can override templates with -t.

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client \
  -t ./my-templates
Enter fullscreen mode Exit fullscreen mode

How do you generate a client SDK from an OpenAPI spec?

Pick a client generator and run generate.

openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-axios \
  -o ./client
Enter fullscreen mode Exit fullscreen mode

For other languages, switch the generator:

openapi-generator-cli generate -i openapi.yaml -g java   -o ./client-java
openapi-generator-cli generate -i openapi.yaml -g python -o ./client-python
openapi-generator-cli generate -i openapi.yaml -g go     -o ./client-go
Enter fullscreen mode Exit fullscreen mode

How do you generate server stubs?

Choose a server generator. For Spring Boot:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g spring \
  -o ./server-spring
Enter fullscreen mode Exit fullscreen mode

The generated output includes controllers and request models based on your spec. You implement the handler logic.

What is the difference between OpenAPI Generator and Swagger Codegen?

OpenAPI Generator was forked from Swagger Codegen in May 2018 by more than 40 contributors. The projects share a common base, but OpenAPI Generator now has its own roadmap, generators, templates, and release cycle.

How do you generate a PHP SDK from an OpenAPI spec?

Use the php generator:

openapi-generator-cli generate \
  -i openapi.yaml \
  -g php \
  -o ./client-php
Enter fullscreen mode Exit fullscreen mode

Before generating, run:

openapi-generator-cli list
Enter fullscreen mode Exit fullscreen mode

Use the list output to confirm the exact PHP generator name and check for framework-specific PHP options.

Top comments (0)