使用Swagger Codegen CLI生成OpenAPI 3.0 Java客户端时出现io.swagger.v3.oas.annotations.media包不存在错误的求助

这个io.swagger.v3.oas.annotations.media does not exist错误是从Swagger 2.0切换到OpenAPI 3.0生成客户端时的典型问题，核心原因是生成的代码依赖OpenAPI 3.0的注解库，但你的项目没有引入对应的依赖，另外也要检查自定义模板是否残留了旧的Swagger 2.0注解引用。下面是具体的解决步骤：

1. 添加OpenAPI 3注解依赖 #

Swagger Codegen 3.x生成OpenAPI 3.0代码时，会使用io.swagger.v3.oas.annotations系列的注解，这些注解不在你当前的依赖配置中。在你的Gradle dependencies块中添加以下依赖（版本和你使用的swagger-gradle-plugin保持一致即可）：

dependencies {
    // 保留你原有的依赖，新增以下两行
    implementation "io.swagger.core.v3:swagger-annotations:2.1.10"
    implementation "io.swagger.core.v3:swagger-models:2.1.10"
}

2. 检查自定义Mustache模板 #

你使用了自定义模板目录，要确保模板文件没有引用旧的Swagger 2.0注解：

• 旧的Swagger 2.0注解属于io.swagger.annotations包，比如@ApiModelProperty
• OpenAPI 3.0对应的注解属于io.swagger.v3.oas.annotations包，比如@Schema

打开你的pojo.mustache或其他模板文件，检查是否有类似@ApiModelProperty的注解，替换成OpenAPI 3.0的写法。例如：

// 旧的Swagger 2.0写法
@ApiModelProperty(value = "{{{description}}}", required = {{required}})

// 替换为OpenAPI 3.0写法
@Schema(description = "{{{description}}}", required = {{required}})

同时确认generatedAnnotation.mustache等其他模板没有导入旧的注解包。

3. 清理并重新生成代码 #

先清理之前生成的旧代码，再重新运行生成任务：

./gradlew clean doCodeGenSdk build

额外检查点 #

• 确认你的Swagger配置文件中的参数没有冲突，比如java8: true、serializableModel: true这些设置都是兼容OpenAPI 3.0的
• 你使用的resttemplate库完全支持OpenAPI 3.0，无需更换

按照这些步骤操作后，导入错误应该就能解决了。

内容的提问来源于stack exchange，提问作者Alok Nath Saha