如何解决Spring Boot 3.3.0与Swagger（Springfox）的类路径兼容性问题？

Springfox 2.9.2是停止维护的老旧版本，仅支持Spring Boot 2.x及更低版本，完全不兼容基于Spring Framework 6的Spring Boot 3.3.0。冲突核心在于：

• Springfox 2.9.2依赖的org.springframework.plugin版本过低，与Spring Boot 3.3.0自带的Spring Framework组件（如org.springframework.util.Assert）方法签名不匹配
• Spring Boot 3.x要求Java 17+，而Springfox 2.9.2的设计未考虑高版本Java和Spring Framework的API变化

优先推荐使用Springdoc OpenAPI，它是Spring生态官方认可的Swagger替代方案，完全兼容Spring Boot 3.x，且持续维护。

方案1：替换为Springdoc OpenAPI（推荐） #

步骤1：移除原Springfox依赖 #

删除pom.xml中以下内容：

<!-- SWAGGER DOCUMENTACAO -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

步骤2：添加Springdoc依赖 #

在pom.xml的<dependencies>中加入适配Spring Boot 3.3.0的版本：

<!-- Springdoc OpenAPI 3 依赖 -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.5.0</version>
</dependency>

步骤3：访问API文档 #

启动应用后，访问以下地址查看Swagger UI：

• http://localhost:8080/swagger-ui/index.html（Springdoc默认访问路径）

可选：自定义API配置 #

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

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("My First Web API")
                        .version("0.0.1-SNAPSHOT")
                        .description("Demo API documentation"));
    }
}

方案2：强行使用Springfox（不推荐） #

Springfox官方已停止维护，无官方兼容Spring Boot 3.x的版本。部分第三方fork版本声称兼容，但存在稳定性风险，不建议用于生产环境。若坚持使用，需替换为第三方fork的依赖，但后续可能遇到更多兼容性问题。

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.3.0</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>dio</groupId>
    <artifactId>my-first-web-api</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>my-first-web-api</name>
    <description>Demo project for Spring Boot</description>
    <properties>
        <java.version>22</java.version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
        
        <!-- Springdoc OpenAPI 3 依赖 -->
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
            <version>2.5.0</version>
        </dependency>

    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

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