openapi-generator

Original：🇺🇸 English
Translated

OpenAPI Generator - generate clients and servers from OpenAPI specs USE WHEN: user mentions "OpenAPI Generator CLI", "generate Java client", "generate Spring server", "openapi-generator-cli", "openapi-generator-maven-plugin", asks about "generate server from OpenAPI", "OpenAPI Generator templates" DO NOT USE FOR: TypeScript-only generation - use `openapi-codegen` instead; Writing OpenAPI specs - use `openapi` instead; GraphQL - use `graphql-codegen` instead

3installs
Sourceclaude-dev-suite/claude-dev-suite
Added on

NPX Install

npx skill4agent add claude-dev-suite/claude-dev-suite openapi-generator

Tags

Translated version includes tags in frontmatter
openapi-generatorapi-code-generationcli-usagemaven-pluginspring-server-generation

SKILL.md Content

View Translation Comparison →

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

bash
npm install @openapitools/openapi-generator-cli -g
# or
brew install openapi-generator

Generate TypeScript Client

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

Generate TypeScript Axios Client

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

Generate Java Client

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

Generate Spring Server

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

NPM Script Integration

package.json

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

Maven Plugin

xml
<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

GeneratorDescription
typescript-fetchTypeScript with Fetch API
typescript-axiosTypeScript with Axios
javaJava client
springSpring Boot server
pythonPython client
goGo 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-PatternWhy It's BadSolution
Committing generated codeMerge conflicts, stale codeAdd to .gitignore, generate in build
Not pinning generator versionBreaking changes between versionsLock version in package.json/pom.xml
Editing generated filesLost on regenerationExtend classes or use custom templates
No spec validation before generationInvalid code generatedUse @redocly/cli lint first
Generating entire API for one endpointBloated clientUse tags or paths filter
Missing operationId in specPoor method namesAdd operationId to all operations
Not configuring additional propertiesSuboptimal outputUse additionalProperties for customization
Generating without .openapi-generator-ignoreOverwrites custom filesAdd ignore file for manual code

Quick Troubleshooting

IssuePossible CauseSolution
Generation failsInvalid OpenAPI specValidate with 
@redocly/cli lint
Missing methodsNo operationId in specAdd operationId to all paths
Compilation errors in generated codeSpec type mismatchCheck schema types, run with --skip-validate-spec to debug
Wrong package namesConfig not setUse --additional-properties for package config
Duplicate model namesSame schema name in different tagsRename schemas or use x-model-name
Maven plugin not runningWrong phase or configurationCheck plugin execution phase
NPM global command not foundNot installed globallyInstall with npm install -g or use npx
Generated code has wrong typesGenerator doesn't support typeUse custom templates or different generator