OpenAPI Generator - Quick Reference

When to Use This Skill

• Generate type-safe API clients from OpenAPI specs

• Generate server stubs from OpenAPI specs

• Maintain sync between API and code

• Multi-language client generation (Java, Python, Go, etc.)

• Spring Boot server generation

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: openapi-generator for comprehensive documentation.

CLI Usage

Install

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

or

brew install openapi-generator

Generate TypeScript Client

openapi-generator-cli generate
-i api.yaml
-g typescript-fetch
-o ./generated/api
--additional-properties=supportsES6=true,typescriptThreePlus=true

Generate TypeScript Axios Client

openapi-generator-cli generate
-i api.yaml
-g typescript-axios
-o ./generated/api

Generate Java Client

openapi-generator-cli generate
-i api.yaml
-g java
-o ./generated/api
--additional-properties=library=webclient,dateLibrary=java8

Generate Spring Server

openapi-generator-cli generate
-i api.yaml
-g spring
-o ./generated/server
--additional-properties=interfaceOnly=true,useSpringBoot3=true

NPM Script Integration

package.json

{ "scripts": { "generate:api": "openapi-generator-cli generate -i ./api/openapi.yaml -g typescript-fetch -o ./src/generated/api" } }

Maven Plugin

<plugin> <groupId>org.openapitools</groupId> <artifactId>openapi-generator-maven-plugin</artifactId> <version>7.0.0</version> <executions> <execution> <goals> <goal>generate</goal> </goals> <configuration> <inputSpec>${project.basedir}/src/main/resources/api.yaml</inputSpec> <generatorName>spring</generatorName> <configOptions> <interfaceOnly>true</interfaceOnly> <useSpringBoot3>true</useSpringBoot3> </configOptions> </configuration> </execution> </executions> </plugin>

Common Generators

Generator Description

typescript-fetch TypeScript with Fetch API

typescript-axios TypeScript with Axios

java Java client

spring Spring Boot server

python Python client

go Go client

When NOT to Use This Skill

• TypeScript-only projects (use openapi-codegen with openapi-typescript instead)

• Writing OpenAPI specifications (use openapi skill)

• GraphQL code generation (use graphql-codegen skill)

• tRPC projects (use trpc skill)

• Simple type-only generation (openapi-typescript is lighter)

Anti-Patterns

Anti-Pattern Why It's Bad Solution

Committing generated code Merge conflicts, stale code Add to .gitignore, generate in build

Not pinning generator version Breaking changes between versions Lock version in package.json/pom.xml

Editing generated files Lost on regeneration Extend classes or use custom templates

No spec validation before generation Invalid code generated Use @redocly/cli lint first

Generating entire API for one endpoint Bloated client Use tags or paths filter

Missing operationId in spec Poor method names Add operationId to all operations

Not configuring additional properties Suboptimal output Use additionalProperties for customization

Generating without .openapi-generator-ignore Overwrites custom files Add ignore file for manual code

Quick Troubleshooting

Issue Possible Cause Solution

Generation fails Invalid OpenAPI spec Validate with @redocly/cli lint

Missing methods No operationId in spec Add operationId to all paths

Compilation errors in generated code Spec type mismatch Check schema types, run with --skip-validate-spec to debug

Wrong package names Config not set Use --additional-properties for package config

Duplicate model names Same schema name in different tags Rename schemas or use x-model-name

Maven plugin not running Wrong phase or configuration Check plugin execution phase

NPM global command not found Not installed globally Install with npm install -g or use npx

Generated code has wrong types Generator doesn't support type Use custom templates or different generator