swagger codegen参数介绍

一、基础通用命令格式（所有语言通用）

1. CLI 原生 jar 通用格式

java -jar swagger-codegen-cli.jar generate \
  -i 输入的swagger.json/yaml \
  -l 语言标识 \
  -o 输出目录 \
  --additional-properties=参数1=值1,参数2=值2...

参数含义：

• -i：你的 OpenAPI 规范文件（swagger2.0 json/yaml）
• -l：语言 / 框架代号（最核心，下面全部给你列好）
• -o：生成代码输出文件夹
• --additional-properties：自定义配置（包名、注解、日期、序列化、接口风格等）

2. 全局通用通用参数（所有生成都能用）

--additional-properties
modelPackage=com.xxx.model,        # 实体类Model包路径
apiPackage=com.xxx.api,            # 接口API包路径
invokerPackage=com.xxx.sdk,        # 客户端核心工具包
java8=true,                        # 启用Java8新特性（LocalDate/LocalDateTime）
dateLibrary=java8,                 # 日期类型库
useBeanValidation=true,            # 生成JSR380校验注解(@NotBlank等)
generateModelDocumentation=true,  # 生成模型注释
generateApiDocumentation=true,     # 生成接口注释
withXml=false,                     # 关闭XML序列化（微服务基本都不用）
useSpringBoot3=true                # SpringBoot3专用（新版）

二、Swagger Codegen 常用语言完整清单（含代号 + 参数 + 完整命令）

全部是开发最常用，按后端服务端、客户端 SDK、前端 TS 分类，每个都附带可直接复制完整命令。

一、Java 系列（后端最常用）

1. spring（Spring Boot 服务端骨架）

语言标识：spring
生成：Controller、接口定义、Model、空方法体，只需要你补业务逻辑

java -jar swagger-codegen-cli.jar generate \
  -i api.yaml \
  -l spring \
  -o ./spring-boot-server \
  --additional-properties=modelPackage=com.example.model,apiPackage=com.example.controller,java8=true,dateLibrary=java8,useBeanValidation=true,withXml=false

常用额外配置：

• useSpringBoot3=true：适配 SpringBoot 3.x
• interfaceOnly=true：只生成接口，不生成实现类
• skipDefaultInterface=true

2. java（通用 Java 客户端 SDK，OkHttp）

语言标识：java
生成纯 Java 调用 SDK，无框架依赖，OkHttp 客户端

java -jar swagger-codegen-cli.jar generate \
  -i api.yaml \
  -l java \
  -o ./java-sdk \
  --additional-properties=modelPackage=com.example.model,apiPackage=com.example.api,invokerPackage=com.example.sdk,java8=true,dateLibrary=java8

3. retrofit（Retrofit2 + OkHttp 安卓 / Java 客户端）

语言标识：retrofit
安卓开发首选 SDK 生成

java -jar swagger-codegen-cli.jar generate \
  -i api.yaml \
  -l retrofit \
  -o ./retrofit-sdk \
  --additional-properties=modelPackage=com.example.model,apiPackage=com.example.api,invokerPackage=com.example.sdk,java8=true

二、Python 系列

8. python（通用 Python SDK）

语言标识：python

java -jar swagger-codegen-cli.jar generate \
  -i api.yaml \
  -l python \
  -o ./python-sdk \
  --additional-properties=packageName=openapi_client

9. python-flask（Flask 服务端骨架）

语言标识：python-flask

三、Swagger Codegen v3 新版区别（OpenAPI3.0 专用）

旧版 swagger-codegen-cli 只完美支持 Swagger2.0(OpenAPI2.0)
如果你是 OpenAPI 3.0 yaml，请用 v3 版本，-l 语言标识基本完全不变，只是 jar 包换了：

java -jar swagger-codegen-cli-v3.jar generate \
  -i openapi3.yaml \
  -l spring \
  -o ./output

四、Maven 插件版（Java 项目内置生成，不用手动下 jar）

企业项目最常用，直接写 pom.xml，maven 一键生成代码

swagger-codegen-maven-plugin 2.x

<plugin>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-codegen-maven-plugin</artifactId>
    <version>2.3.1</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <!-- 你的swagger文件路径 -->
        <inputSpec>src/main/resources/api.yaml</inputSpec>
        <!-- 语言标识 和上面完全一致 -->
        <language>java</language>
        <output>target/generated-sources</output>
        <additionalProperties>
            modelPackage=com.example.model,
            apiPackage=com.example.api,
            invokerPackage=com.example.sdk,
            java8=true,
            dateLibrary=java8,
            useBeanValidation=true,
            withXml=false
        </additionalProperties>
    </configuration>
</plugin>

执行命令：

mvn clean generate-sources

五、避坑总结 + 版本提醒

 

1. Swagger Codegen 已经官方停更
   新项目强烈建议迁移 OpenAPI Generator，语言标识 99% 完全通用，我也可以顺便给你一套一模一样参数清单。
2. 生成 Spring 代码默认会带大量冗余 XML 配置，必须加 withXml=false
3. 时间字段默认生成 Date，加 java8=true,dateLibrary=java8 自动变成 LocalDateTime
4. 前端 typescript-axios 是目前国内前后端对接最通用模板，没有之一
5. 如果你生成的代码接口缺少注释、字段不全，检查 swagger 文件是否写全description