Spring Boot3.0+Gradle集成Springfox Swagger2遇类缺失错误求助

问题背景 #

在Gradle构建的Spring Boot 3.0.1项目中尝试集成Swagger，测试Springfox 3.0.0及旧版本均无法正常启动，核心原因是Springfox已停止维护，完全不兼容Spring Boot 3.x版本。

终端错误信息 #

当前Build.gradle配置 #

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.0.1'
    id 'io.spring.dependency-management' version '1.1.0'
}

group = 'practice.example'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '19'

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
    implementation("io.springfox:springfox-swagger2:3.0.0")
}

tasks.named('test') {
    useJUnitPlatform()
}

主Java文件代码 #

package practice.example.crud_practice;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@SpringBootApplication
@EnableSwagger2
@RestController
public class CrudPracticeApplication {

    public static void main(String[] args) {
        SpringApplication.run(CrudPracticeApplication.class, args);
    }

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.any()) // 包含所有控制器
            .paths(PathSelectors.any())
            .build();
      }

      @GetMapping("/hello")
      public String hello(@RequestParam(value = "name", defaultValue = "World") String name) {
          return String.format("Hello %s!", name);
      }
}

关键现象 #

注释掉代码中的@EnableSwagger2注解后，项目可正常启动，无错误。

解决方案：改用SpringDoc OpenAPI #

SpringDoc是Spring Boot 3.x官方推荐的Swagger替代方案，完全适配Spring Framework 6及Jakarta EE规范，维护活跃。

1. 修改Gradle依赖 #

替换原Springfox依赖为SpringDoc：

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
    // SpringDoc OpenAPI依赖
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.2.0'
}

2. 简化主代码 #

移除原有的@EnableSwagger2注解和Docket Bean，SpringDoc会自动扫描接口生成文档：

package practice.example.crud_practice;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@SpringBootApplication
@RestController
public class CrudPracticeApplication {

    public static void main(String[] args) {
        SpringApplication.run(CrudPracticeApplication.class, args);
    }

      @GetMapping("/hello")
      public String hello(@RequestParam(value = "name", defaultValue = "World") String name) {
          return String.format("Hello %s!", name);
      }
}

3. （可选）自定义API文档配置 #

如果需要自定义文档标题、版本等信息，可添加OpenAPI配置类：

package practice.example.crud_practice;

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("CRUD Practice API")
                        .version("0.0.1-SNAPSHOT")
                        .description("Spring Boot 3.x集成OpenAPI示例文档"));
    }
}

4. 访问文档界面 #

启动项目后，访问http://localhost:8080/swagger-ui.html即可查看自动生成的API文档。

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