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 |
