OpenAPI Generator 使用指南

OpenAPI Generator 是一个强大的工具，可以从 OpenAPI 规范自动生成多种语言的客户端、服务端代码和 API 文档。

🔧 基本用法

安装

bash

# 全局安装
npm install @openapitools/openapi-generator-cli -g

# 查看版本
npx @openapitools/openapi-generator-cli version

基本命令

bash

npx @openapitools/openapi-generator-cli generate \
  -i <OpenAPI文件路径> \
  -g <生成器名称> \
  -o <输出目录>

📋 常用生成器

客户端生成器

生成器	语言	推荐度	特点
`typescript-fetch`	TypeScript	⭐⭐⭐⭐⭐	基于 Fetch API，现代化
`typescript-axios`	TypeScript	⭐⭐⭐⭐	基于 Axios，功能丰富
`java`	Java	⭐⭐⭐⭐⭐	成熟稳定，支持多种库
`python`	Python	⭐⭐⭐⭐	支持多种 HTTP 库
`javascript`	JavaScript	⭐⭐⭐	ES5/ES6 支持

服务端生成器

生成器	框架	推荐度	特点
`spring`	Spring Boot	⭐⭐⭐⭐⭐	企业级，功能完整
`nodejs-express-server`	Express.js	⭐⭐⭐⭐	轻量级，易于定制
`python-flask`	Flask	⭐⭐⭐	简单易用
`aspnetcore`	ASP.NET Core	⭐⭐⭐⭐	微软技术栈

🎯 实战示例

TypeScript 客户端

bash

npx @openapitools/openapi-generator-cli generate \
  -i api/openapi.yaml \
  -g typescript-fetch \
  -o generated/typescript-client \
  --additional-properties=npmName=my-api-client,npmVersion=1.0.0,supportsES6=true

常用参数

基础配置高级配置

bash

--additional-properties=\
npmName=my-api-client,\
npmVersion=1.0.0,\
supportsES6=true,\
withInterfaces=true

bash

--additional-properties=\
npmName=my-api-client,\
npmVersion=1.0.0,\
supportsES6=true,\
withInterfaces=true,\
stringEnums=true,\
useSingleRequestParameter=true,\
modelPropertyNaming=camelCase

生成的代码结构

typescript-client/
├── apis/
│   ├── AuthApi.ts
│   ├── UserApi.ts
│   └── index.ts
├── models/
│   ├── User.ts
│   ├── AuthRequest.ts
│   └── index.ts
├── runtime.ts
└── index.ts

Java 客户端

bash

npx @openapitools/openapi-generator-cli generate \
  -i api/openapi.yaml \
  -g java \
  -o generated/java-client \
  --package-name com.example.api.client \
  --additional-properties=library=okhttp-gson,java8=true,dateLibrary=java8

支持的库

库名	描述	适用场景
`okhttp-gson`	OkHttp + Gson	通用推荐
`retrofit2`	Retrofit 2	Android 开发
`resttemplate`	Spring RestTemplate	Spring 项目
`webclient`	Spring WebClient	响应式项目

Spring Boot 服务端

bash

npx @openapitools/openapi-generator-cli generate \
  -i api/openapi.yaml \
  -g spring \
  -o generated/spring-server \
  --package-name com.example.api \
  --api-package com.example.api.controller \
  --model-package com.example.api.model \
  --additional-properties=interfaceOnly=true,useTags=true,java8=true

关键参数说明

interfaceOnly=true - 只生成接口，便于实现
useTags=true - 按标签分组接口
delegatePattern=true - 使用委托模式
java8=true - 使用 Java 8 特性

⚙️ 配置文件方式

创建配置文件

创建 config.yaml：

yaml

generatorName: typescript-fetch
inputSpec: api/openapi.yaml
outputDir: generated/typescript-client
packageName: my-api-client
additionalProperties:
  npmName: my-api-client
  npmVersion: 1.0.0
  supportsES6: true
  withInterfaces: true
  stringEnums: true

使用配置文件

bash

npx @openapitools/openapi-generator-cli generate -c config.yaml

🔍 查看可用选项

列出所有生成器

bash

npx @openapitools/openapi-generator-cli list

查看特定生成器的配置选项

bash

npx @openapitools/openapi-generator-cli config-help -g typescript-fetch

生成配置模板

bash

npx @openapitools/openapi-generator-cli config-help -g spring --write-config spring-config.json

🚀 批量生成脚本

创建 generate-all.sh：

bash

#!/bin/bash

echo "🚀 Generating multiple clients..."

# TypeScript 客户端
npx @openapitools/openapi-generator-cli generate \
  -i api/openapi.yaml \
  -g typescript-fetch \
  -o clients/typescript \
  --additional-properties=npmName=my-api-client,supportsES6=true

# Java 客户端
npx @openapitools/openapi-generator-cli generate \
  -i api/openapi.yaml \
  -g java \
  -o clients/java \
  --package-name com.example.api.client \
  --additional-properties=library=okhttp-gson,java8=true

# Python 客户端
npx @openapitools/openapi-generator-cli generate \
  -i api/openapi.yaml \
  -g python \
  -o clients/python \
  --package-name api_client

# Spring 服务端
npx @openapitools/openapi-generator-cli generate \
  -i api/openapi.yaml \
  -g spring \
  -o servers/spring \
  --package-name com.example.api \
  --additional-properties=interfaceOnly=true,useTags=true

echo "✅ All clients generated successfully!"

📝 最佳实践

1. 文件组织

project/
├── api/
│   └── openapi.yaml          # OpenAPI 规范
├── generated/                # 生成的代码
│   ├── typescript-client/
│   ├── java-client/
│   └── spring-server/
├── configs/                  # 配置文件
│   ├── typescript.yaml
│   ├── java.yaml
│   └── spring.yaml
└── scripts/                  # 生成脚本
    └── generate-all.sh

2. .gitignore 配置

gitignore

# 生成的代码
generated/
clients/
servers/

# 配置文件中的敏感信息
**/application-secret.properties

3. 版本管理

bash

# 为生成的包指定版本
--additional-properties=npmVersion=1.2.3,artifactVersion=1.2.3

4. 自定义模板

bash

# 使用自定义模板
npx @openapitools/openapi-generator-cli generate \
  -i api/openapi.yaml \
  -g typescript-fetch \
  -o generated/typescript-client \
  -t custom-templates/typescript/

⚠️ 常见问题

1. 内存不足

bash

# 增加 Node.js 内存限制
NODE_OPTIONS="--max-old-space-size=4096" npx @openapitools/openapi-generator-cli generate ...

2. 编码问题

bash

# 指定文件编码
--additional-properties=sourceEncoding=UTF-8

3. 生成失败

bash

# 启用详细日志
--verbose

OpenAPI Generator 使用指南 ​

🔧 基本用法 ​

安装 ​

基本命令 ​

📋 常用生成器 ​

客户端生成器 ​

服务端生成器 ​

🎯 实战示例 ​

TypeScript 客户端 ​

常用参数 ​

生成的代码结构 ​

Java 客户端 ​

支持的库 ​

Spring Boot 服务端 ​

关键参数说明 ​

⚙️ 配置文件方式 ​

创建配置文件 ​

使用配置文件 ​

🔍 查看可用选项 ​

列出所有生成器 ​

查看特定生成器的配置选项 ​

生成配置模板 ​

🚀 批量生成脚本 ​

📝 最佳实践 ​

1. 文件组织 ​

2. .gitignore 配置 ​

3. 版本管理 ​

4. 自定义模板 ​

⚠️ 常见问题 ​

1. 内存不足 ​

2. 编码问题 ​

3. 生成失败 ​

🔗 相关链接 ​

OpenAPI Generator 使用指南

🔧 基本用法

安装

基本命令

📋 常用生成器

客户端生成器

服务端生成器

🎯 实战示例

TypeScript 客户端

常用参数

生成的代码结构

Java 客户端

支持的库

Spring Boot 服务端

关键参数说明

⚙️ 配置文件方式

创建配置文件

使用配置文件

🔍 查看可用选项

列出所有生成器

查看特定生成器的配置选项

生成配置模板

🚀 批量生成脚本

📝 最佳实践

1. 文件组织

2. .gitignore 配置

3. 版本管理

4. 自定义模板

⚠️ 常见问题

1. 内存不足

2. 编码问题

3. 生成失败

🔗 相关链接