迁移至Jakarta后，如何用Maven生成兼容Swagger-UI的JSON？

问题根源 #

旧的com.github.kongchen插件基于Swagger 2.0注解体系解析，而io.swagger.core.v3的Jakarta版完全适配OpenAPI 3.x规范——尽管部分注解名称和Swagger 2.0一致，但底层解析逻辑不兼容，直接复用旧注解会导致插件无法识别，最终生成的文档缺失关键内容。

分步修复方案 #

1. 统一依赖与插件版本 #

避免版本冲突，在pom.xml中确保Swagger核心依赖和插件版本一致：

<!-- OpenAPI 3.x Jakarta核心依赖 -->
<dependency>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-jaxrs2-jakarta</artifactId>
    <version>2.2.15</version> <!-- 与插件版本保持一致，选最新稳定版也可 -->
</dependency>

<!-- Maven插件配置 -->
<build>
    <plugins>
        <plugin>
            <groupId>io.swagger.core.v3</groupId>
            <artifactId>swagger-maven-plugin-jakarta</artifactId>
            <version>2.2.15</version>
            <executions>
                <execution>
                    <phase>compile</phase>
                    <goals>
                        <goal>resolve</goal>
                    </goals>
                    <configuration>
                        <outputFileName>openapi</outputFileName>
                        <outputPath>${project.build.directory}</outputPath>
                        <!-- 必须覆盖所有含API/模型注解的包，否则会漏扫 -->
                        <resourcePackages>
                            <package>com.yourcompany.api</package>
                            <package>com.yourcompany.model</package>
                        </resourcePackages>
                        <prettyPrint>true</prettyPrint>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

2. 替换为OpenAPI 3.x注解 #

废弃旧的io.swagger.annotations包下的注解，全部改用io.swagger.v3.oas.annotations包的注解，重点调整以下内容：

• 标签（Tags）：用@Tag替代旧的@Api，直接标注在API类上：

  @Tag(name = "用户管理", description = "用户增删改查相关接口")
  @Path("/users")
  public class UserResource {
      // ...
  }
  

• 响应模型与Content字段：旧@ApiOperation的response参数在3.x中失效，需用@Content+@Schema明确指定响应结构：
  旧Swagger 2.0写法：

  @ApiOperation(value = "获取用户详情", response = User.class)
  @ApiResponses(value = {
      @ApiResponse(code = 200, message = "请求成功")
  })
  

  新OpenAPI 3.x Jakarta写法：

  @Operation(summary = "获取用户详情")
  @ApiResponses(value = {
      @ApiResponse(responseCode = "200", description = "请求成功",
          content = @Content(mediaType = "application/json",
              schema = @Schema(implementation = User.class)))
  })
  

3. 清理缓存重新构建 #

执行命令清理旧构建产物，重新生成OpenAPI文档：

mvn clean compile

验证生成结果 #

查看target/openapi.json文件，确认以下内容：

• tags数组包含定义的标签信息
• 接口responses中对应状态码的content字段包含正确的媒体类型和Schema引用
• components.schemas下生成了所有模型类的完整结构

内容的提问来源于stack exchange，提问作者Nephilim