openapi-generator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenAPI Generator - Quick Reference

OpenAPI Generator - 快速参考

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.

从OpenAPI规范生成类型安全的API客户端
从OpenAPI规范生成服务端存根
保持API与代码的同步
多语言客户端生成（Java、Python、Go等）
Spring Boot服务端生成

深度文档: 使用
mcp__documentation__fetch_docs
工具，指定技术为
openapi-generator
以获取完整文档。

CLI Usage

CLI 使用方法

Install

安装

bash

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

bash

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

or

brew install openapi-generator

undefined

brew install openapi-generator

undefined

Generate TypeScript Client

生成TypeScript客户端

bash

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

bash

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

Generate TypeScript Axios Client

生成TypeScript Axios客户端

bash

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

bash

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

Generate Java Client

生成Java客户端

bash

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

bash

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

Generate Spring Server

生成Spring服务端

bash

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

bash

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

NPM Script Integration

NPM 脚本集成

package.json

json

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

json

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

Maven Plugin

Maven 插件

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>

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

常见生成器

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

生成器	描述
typescript-fetch	基于Fetch API的TypeScript客户端
typescript-axios	基于Axios的TypeScript客户端
java	Java客户端
spring	Spring Boot服务端
python	Python客户端
go	Go客户端

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)

仅TypeScript项目（请结合openapi-typescript使用
```
openapi-codegen
```
）
编写OpenAPI规范（请使用
```
openapi
```
工具）
GraphQL代码生成（请使用
```
graphql-codegen
```
工具）
tRPC项目（请使用
```
trpc
```
工具）
仅简单类型生成（openapi-typescript更轻量）

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

反模式	问题所在	解决方案
提交生成的代码	易引发合并冲突、代码过时	添加到.gitignore，在构建阶段生成
未固定生成器版本	版本间可能存在破坏性变更	在package.json/pom.xml中锁定版本
修改生成的文件	重新生成后修改内容会丢失	继承类或使用自定义模板
生成前未验证规范	可能生成无效代码	先使用@redocly/cli进行校验
为单个接口生成完整API	客户端代码臃肿	使用标签或路径过滤
规范中缺少operationId	生成的方法命名不佳	为所有操作添加operationId
未配置额外属性	输出结果不够优化	使用additionalProperties进行自定义配置
生成时未使用.openapi-generator-ignore	会覆盖自定义文件	添加忽略文件以保护手动编写的代码

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

问题	可能原因	解决方案
生成失败	OpenAPI规范无效	使用 `@redocly/cli lint` 验证规范
缺少方法	规范中缺少operationId	为所有路径添加operationId
生成的代码编译报错	规范类型不匹配	检查Schema类型，使用--skip-validate-spec参数调试
包名错误	未配置相关参数	使用--additionalProperties配置包名
模型名称重复	不同标签下存在同名Schema	重命名Schema或使用x-model-name
Maven插件未运行	阶段或配置错误	检查插件执行阶段
NPM全局命令找不到	未全局安装	使用npm install -g安装或使用npx
生成的代码类型错误	生成器不支持该类型	使用自定义模板或更换生成器