Spring Boot 3 集成 Swagger 3 出现404错误求助

问题根源 #

Springfox Swagger 3.0.0版本不兼容Spring Boot 3.x——Spring Boot 3基于Jakarta EE规范（替代了旧Java EE），而Springfox 3.0.0仍依赖旧的Java EE相关API，导致Swagger相关端点无法正常加载，触发404错误。

解决方案一：替换为Springdoc OpenAPI（推荐） #

Springdoc是Springfox的官方替代方案，完全适配Spring Boot 3和Jakarta EE，配置更简洁稳定。

1. 修改pom.xml依赖 #

移除原有Springfox依赖，添加Springdoc的starter：

<dependencies>
    <!-- 保留原有web依赖 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <!-- 替换为Springdoc OpenAPI Starter -->
    <dependency>
        <groupId>org.springdoc</groupId>
        <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
        <version>2.2.0</version> <!-- 可选择适配Spring Boot3的最新稳定版 -->
    </dependency>

    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

2. 访问Swagger页面 #

启动项目后，访问以下URL即可打开Swagger UI：
http://localhost:8080/swagger-ui/index.html

解决方案二：临时适配（不推荐，存在兼容性风险） #

如果坚持使用Springfox，可通过添加兼容依赖和配置临时解决，但生产环境不建议采用：

1. 补充pom.xml依赖 #

在原有Springfox依赖基础上，添加Jakarta EE兼容桥接包：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>
<!-- 添加Jakarta兼容桥接 -->
<dependency>
    <groupId>javax.annotation</groupId>
    <artifactId>javax.annotation-api</artifactId>
    <version>1.3.2</version>
</dependency>

2. 添加Swagger配置类 #

创建配置类开启Swagger并指定扫描范围：

package com.example.demo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo")) // 替换为你的Controller所在包路径
                .paths(PathSelectors.any())
                .build();
    }
}

3. 尝试访问路径 #

启动后访问以下地址：
http://localhost:8080/swagger-ui/ 或 http://localhost:8080/swagger-ui/index.html

注意事项 #

• Springfox官方目前未发布支持Spring Boot3的正式版本，方案二仅为临时 workaround，可能存在未知兼容性问题。
• 使用Springdoc时，可通过application.properties自定义Swagger路径、标题等属性，例如：

springdoc.swagger-ui.path=/docs
springdoc.api-docs.path=/api-docs

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