Spring Boot 3.1.0集成Swagger访问swagger-ui.html出现404问题求助

核心原因 #

Springfox Swagger目前不兼容Spring Boot 3.x版本——Spring Boot 3.x基于Jakarta EE规范（替代原Java EE），而Springfox仍依赖Java EE环境下的Spring MVC包（如javax.servlet），两者基础依赖不兼容，导致Swagger相关资源无法正常加载，最终出现404。

解决方案：替换为Springdoc OpenAPI #

Springdoc是Spring Boot 3.x官方推荐的Swagger替代方案，完全适配Jakarta EE生态，操作步骤如下：

1. 替换pom.xml依赖 #

移除所有Springfox相关依赖，添加Springdoc的Starter：

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

注：2.x版本适配Spring Boot 3.x，可根据需求选择对应兼容版本

2. 简化配置（无需额外启动类注解） #

Springdoc默认自动完成配置，不需要像Springfox那样添加@EnableSwagger2类注解。如果需要自定义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("项目API文档")
                        .version("1.0")
                        .description("项目接口说明"));
    }
}

3. 访问API文档页面 #

启动项目后，访问以下地址：

• Swagger UI页面：http://localhost:8080/swagger-ui/index.html
• OpenAPI规范文档：http://localhost:8080/v3/api-docs

额外排查点（替换后仍有问题时） #

• 检查自定义WebMvcConfigurer是否拦截Swagger路径，需放行相关资源：

  @Override
  public void addResourceHandlers(ResourceHandlerRegistry registry) {
      registry.addResourceHandler("/swagger-ui/**")
              .addResourceLocations("classpath:/META-INF/resources/webjars/springdoc-openapi-ui/");
      registry.addResourceHandler("/v3/api-docs/**")
              .addResourceLocations("classpath:/META-INF/resources/");
  }
  

• 若开启Spring Security，需放行Swagger相关路径：

  @Override
  protected void configure(HttpSecurity http) throws Exception {
      http.authorizeHttpRequests(auth -> auth
              .requestMatchers("/swagger-ui/**", "/v3/api-docs/**")
              .permitAll()
              .anyRequest().authenticated());
  }
  

• 确认控制台输出的项目启动端口是否为8080，避免端口冲突导致访问失败。

内容的提问来源于stack exchange，提问作者berry.11