swagger codegen 详解

Swagger Codegen 详解

Swagger Codegen 是 Swagger（现归属于 OpenAPI 生态）官方开源的代码生成工具，核心能力：根据 OpenAPI/Swagger 接口规范文件（yaml/json），自动批量生成客户端 SDK、服务端骨架代码、API 文档，彻底减少手写重复接口代码、解决前后端接口不一致问题Swagger。

 

它是 Swagger 三件套（Editor 写规范、UI 可视化文档、Codegen 生成代码）里的代码生成核心工具。

一、核心作用（三大生成能力）

1. 生成客户端 SDK（最常用）

根据接口定义，生成多语言完整调用客户端，包含：请求方法、参数封装、数据模型（Model）、异常处理、请求工具封装，前端 / 第三方服务直接引入调用，不用手写 HTTP 请求、参数拼接、实体类。
支持语言：Java、Python、Go、PHP、TypeScript (Angular/Axios)、Swift、Kotlin、C#、JS、Ruby 等几乎主流语言与主流 HTTP 框架（Retrofit、OkHttp、Feign）Swagger。

2. 生成服务端存根（Server Stub）

生成后端项目基础骨架代码：Controller、接口方法定义、入参出参实体、路由结构、空方法体。
后端开发者只需要填充业务逻辑即可，不用手写接口定义、实体、路由；保证接口定义与服务代码严格对齐。
支持框架：Spring Boot、JAX-RS、Go Server、Node.js、Flask、ASP.NET Core 等Swagger。

3. 生成静态 API 文档

导出 HTML、Markdown、纯文本格式离线接口文档，可直接部署、归档。

二、版本与现状

1. 2.x：旧版，io.swagger 包，仅支持 OpenAPI 2.0（原 Swagger 2.0） 规范。
2. 3.x：新版，io.swagger.codegen.v3，支持 OpenAPI 3.0/3.1，兼容旧版规范。
3. 重要后续项目：OpenAPI Generator
    
   官方后续不再重点维护 Swagger Codegen，全部功能迁移升级为 OpenAPI Generator（社区主力维护、生态更全、Bug 修复更快、模板更丰富），用法几乎完全兼容，新项目优先用 OpenAPI Generator。

三、工作原理

基于 Mustache 模板引擎工作：

1. 解析输入的 OpenAPI 规范文件（yaml/json），提取接口路径、请求方式、参数、返回体、模型结构；
2. 加载对应语言 / 框架的内置代码模板；
3. 填充数据、批量渲染生成完整源码、包结构、配置文件。

同时支持自定义模板，修改生成代码风格、包名、注解、格式适配自身项目规范。

四、使用方式（命令行最简示例）

1. 运行方式

• JAR 包直接运行（最通用）
• Docker 镜像
• Maven/Gradle 插件（Java 项目集成到构建流程）
• 在线网页生成

 

2. 基础命令（CLI）

# 格式
java -jar swagger-codegen-cli.jar generate \
  -i 接口规范文件.yaml \    # 输入：你的openapi定义文件
  -l 目标语言/框架 \       # 输出语言，如java、python、spring、typescript-axios
  -o 输出代码文件夹 \      # 生成代码存放目录
  【可选配置：包名、是否生成测试、日期工具类等】

示例：生成 Spring Boot 服务端代码

java -jar swagger-codegen-cli.jar generate \
  -i api.yaml \
  -l spring \
  -o ./spring-service \
  --additional-properties=java8=true,modelPackage=com.demo.model,apiPackage=com.demo.api

示例：生成 TypeScript Axios 前端客户端

java -jar swagger-codegen-cli.jar generate \
  -i api.yaml \
  -l typescript-axios \
  -o ./ts-sdk

五、优缺点

优点

1. 彻底统一接口：前后端、多端全部基于同一份规范，无文档与代码不一致；
2. 极大提效：省去手写实体、接口、请求封装、SDK、重复 CRUD 代码；
3. 多端复用：一份规范，多语言 / 多平台一键出代码；
4. 可定制化：自定义模板适配公司代码规范、注解、架构。

缺点

1. 生成代码偏通用模板化，复杂业务逻辑、自定义拦截 / 鉴权、业务封装仍需二次修改；
2. 旧版 Swagger Codegen 官方维护停滞，部分语言新版本支持滞后；
3. 复杂嵌套模型、特殊校验规则生成效果一般。

六、与 OpenAPI Generator 区别（必看）

 

 

对比项	Swagger Codegen	OpenAPI Generator
维护方	原 Swagger 官方，现已停更	社区 fork 升级，持续活跃维护
OpenAPI 支持	3.x 仅支持 3.0，不支持 3.1	全支持 3.0/3.1，兼容 2.0
语言 / 框架数量	较少	更多、更新框架、更多客户端
Bug 修复 / 新特性	缓慢	频繁更新、问题修复快
项目建议	老项目兼容维护	所有新项目首选

 

七、典型业务场景

1. 微服务多服务间对接，一键生成调用 SDK；
2. 后端先定义 API 规范，自动生成 Spring Boot 骨架；
3. 前端根据后端 OpenAPI，自动生成 TS 接口请求 SDK；
4. 多端（APP / 小程序 / 后台）统一接口客户端生成；
5. 遗留接口批量标准化、自动补全 SDK。