Spring Boot 3.0+JDK 17 Springfox迁移到SpringDoc

为什么需要迁移？

随着Spring Boot 3.0和JDK 17的发布，开发者可以享受更快的性能、更好的模块化支持以及现代Java生态的新特性。然而，升级过程中一个常见的问题是：原本基于Springfox（Swagger）的API文档工具不再兼容新环境。如果你在启动应用时遇到类似以下错误：

org.springframework.beans.factory.UnsatisfiedDependencyException: 
Error creating bean with name 'apiDescriptionReader'...

解决方案：拥抱SpringDoc OpenAPI

SpringDoc是Springfox的现代替代品，支持以下特性：

• 原生兼容Spring Boot 3.0和JDK 17。

• 支持OpenAPI 3规范。

• 活跃的社区维护和持续更新。

• SpringDoc官方文档

• OpenAPI 3规范指南

---

迁移步骤详解

步骤1：移除Springfox依赖

在pom.xml中删除所有Springfox相关依赖：

    io.springfox
    springfox-swagger2
    2.7.0


    io.springfox
    springfox-swagger-ui
    2.7.0

步骤2：添加SpringDoc依赖

引入SpringDoc官方库：

    org.springdoc
    springdoc-openapi-starter-webmvc-ui
    2.1.0 

步骤3：配置OpenAPI基本信息

创建配置类，定义API文档的元数据：

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.info.Info;
import org.springframework.context.annotation.Configuration;

@Configuration
@OpenAPIDefinition(
    info = @Info(
        title = "用户服务API",
        version = "1.0",
        description = "基于Spring Boot 3.0和JDK 17"
    )
)
public class OpenApiConfig {
}

步骤4：替换注解

将代码中的Springfox注解替换为SpringDoc的OpenAPI注解：

Springfox注解	SpringDoc注解	示例
@Api	@Tag(name = "模块名")	@Tag(name = "用户管理")
@ApiOperation	@Operation(summary = "...")	@Operation(summary = "创建用户")
@ApiParam	@Parameter(description = "...")	@Parameter(description = "用户ID")
@ApiModelProperty	@Schema(description = "...")	@Schema(description = "用户名")

代码示例： 

@RestController
@Tag(name = "用户管理")
public class UserController {

    @Operation(summary = "获取用户列表")
    @GetMapping("/users")
    public List getUsers() {
        // 业务逻辑
    }

    public static class User {
        @Schema(description = "用户ID")
        private Long id;
        
        @Schema(description = "用户名")
        private String name;
    }
}

步骤5：访问Swagger UI

启动应用后，通过以下URL访问文档：

• OpenAPI JSON：http://localhost:8080/v3/api-docs

• Swagger UI界面：http://localhost:8080/swagger-ui.html