Spring Boot 3集成Swagger 2后无法打开UI页面的解决方法

我创建了一个集成Swagger 2的Spring Boot 3示例项目，启动应用后尝试通过URL http://localhost:8080/swagger-ui.html 打开Swagger UI，却得到了"Whitelabel Error Page"的404错误。

我的配置信息 #

Swagger配置类 #

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2).select()
                .apis(RequestHandlerSelectors.basePackage("com.deprem"))
                .paths(PathSelectors.regex("/.*"))
                .build().apiInfo(apiEndPointsInfo());

    }
    private ApiInfo apiEndPointsInfo() {
        return new ApiInfoBuilder().title("Title")
                .description("Description")
                .contact(new Contact("Name and Surname", "", ""))
                .license("Apache 2.0")
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
                .version("1.0.0")
                .build();
    }
}

pom.xml中的依赖 #

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

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

        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <scope>provided</scope>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.jsoup</groupId>
            <artifactId>jsoup</artifactId>
            <version>1.10.2</version>
        </dependency>

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>3.0.0</version>
        </dependency>

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>3.0.0</version>
        </dependency>

        <dependency>
            <groupId>javax.servlet</groupId>
            <artifactId>javax.servlet-api</artifactId>
            <version>4.0.1</version>
            <scope>provided</scope>
        </dependency>


    </dependencies>

控制台日志 #

2023-02-09T01:08:16.232+03:00  INFO 24272 --- [nio-8080-exec-1] o.s.web.servlet.DispatcherServlet        : Initializing Servlet 'dispatcherServlet'
2023-02-09T01:08:16.232+03:00 DEBUG 24272 --- [nio-8080-exec-1] o.s.web.servlet.DispatcherServlet        : Detected StandardServletMultipartResolver
2023-02-09T01:08:16.232+03:00 DEBUG 24272 --- [nio-8080-exec-1] o.s.web.servlet.DispatcherServlet        : Detected AcceptHeaderLocaleResolver
2023-02-09T01:08:16.232+03:00 DEBUG 24272 --- [nio-8080-exec-1] o.s.web.servlet.DispatcherServlet        : Detected FixedThemeResolver
2023-02-09T01:08:16.233+03:00 DEBUG 24272 --- [nio-8080-exec-1] o.s.web.servlet.DispatcherServlet        : Detected org.springframework.web.servlet.view.DefaultRequestToViewNameTranslator@53b689a4
2023-02-09T01:08:16.233+03:00 DEBUG 24272 --- [nio-8080-exec-1] o.s.web.servlet.DispatcherServlet        : Detected org.springframework.web.servlet.support.SessionFlashMapManager@609759ed
2023-02-09T01:08:16.233+03:00 DEBUG 24272 --- [nio-8080-exec-1] o.s.web.servlet.DispatcherServlet        : enableLoggingRequestDetails='false': request parameters and headers will be masked to prevent unsafe logging of potentially sensitive data
2023-02-09T01:08:16.233+03:00  INFO 24272 --- [nio-8080-exec-1] o.s.web.servlet.DispatcherServlet        : Completed initialization in 1 ms
2023-02-09T01:08:16.239+03:00 DEBUG 24272 --- [nio-8080-exec-1] o.s.web.servlet.DispatcherServlet        : GET "/swagger-ui.html", parameters={}
2023-02-09T01:08:16.245+03:00 DEBUG 24272 --- [nio-8080-exec-1] o.s.w.s.handler.SimpleUrlHandlerMapping  : Mapped to ResourceHttpRequestHandler [classpath [META-INF/resources/], classpath [resources/], classpath [static/], classpath [public/], ServletContext [/]]
2023-02-09T01:08:16.250+03:00 DEBUG 24272 --- [nio-8080-exec-1] o.s.w.s.r.ResourceHttpRequestHandler     : Resource not found
2023-02-09T01:08:16.250+03:00 DEBUG 24272 --- [nio-8080-exec-1] o.s.web.servlet.DispatcherServlet        : Completed 404 NOT_FOUND
2023-02-09T01:08:16.254+03:00 DEBUG 24272 --- [nio-8080-exec-1] o.s.web.servlet.DispatcherServlet        : "ERROR" dispatch for GET "/error", parameters={}
2023-02-09T01:08:16.255+03:00 DEBUG 24272 --- [nio-8080-exec-1] s.w.s.m.m.a.RequestMappingHandlerMapping : Mapped to org.springframework.boot.autoconfigure.web.servlet.error.BasicErrorController#errorHtml(HttpServletRequest, HttpServletResponse)
2023-02-09T01:08:16.276+03:00 DEBUG 24272 --- [nio-8080-exec-1] o.s.w.s.v.ContentNegotiatingViewResolver : Selected 'text/html' given [text/html, text/html;q=0.8]
2023-02-09T01:08:16.281+03:00 DEBUG 24272 --- [nio-8080-exec-1] o.s.web.servlet.DispatcherServlet        : Exiting from "ERROR" dispatch, status 404

application.properties配置 #

spring.mvc.pathmatch.matching-strategy=ant_path_matcher

logging.level.org.springframework.web=DEBUG
logging.level.io.springfox=DEBUG

问题原因及解决方法 #

核心原因 #

Springfox 3.0.0版本不兼容Spring Boot 3，因为Spring Boot 3基于Jakarta EE规范，而Springfox 3.x仍依赖旧的javax.servlet API，同时Swagger UI的访问路径在Springfox 3中也发生了变化。此外，pom.xml中存在冗余依赖，也会导致加载异常。

推荐解决方案：改用SpringDoc OpenAPI（Springfox已停止维护） #

SpringDoc是目前支持Spring Boot 3的主流OpenAPI/Swagger替代方案，步骤如下：

1. 替换依赖：删除所有io.springfox相关依赖，添加SpringDoc的starter依赖：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.2.0</version>
</dependency>

2. 简化配置：删除原有的SwaggerConfig类（SpringDoc无需@EnableSwagger2注解），如果需要自定义API文档信息，可创建如下配置类：

@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("Title")
                        .description("Description")
                        .version("1.0.0")
                        .contact(new Contact().name("Name and Surname"))
                        .license(new License().name("Apache 2.0").url("http://www.apache.org/licenses/LICENSE-2.0.html")));
    }
}

3. 访问Swagger UI：使用新的地址访问：http://localhost:8080/swagger-ui/index.html

备选方案：修复Springfox配置（不推荐，兼容性有限） #

如果坚持使用Springfox，可尝试以下调整：

1. 清理冗余依赖：只保留springfox-boot-starter，删除springfox-swagger2和springfox-swagger-ui（starter已包含这两个依赖）。
2. 替换Servlet依赖：将javax.servlet-api替换为Jakarta版本：

<dependency>
    <groupId>jakarta.servlet</groupId>
    <artifactId>jakarta.servlet-api</artifactId>
    <version>6.0.0</version>
    <scope>provided</scope>
</dependency>

3. 修改访问路径：使用Springfox 3的默认路径访问：http://localhost:8080/swagger-ui/（注意末尾的斜杠）

内容的提问来源于stack exchange，提问作者Sercan Noyan Germiyanoğlu