SpringBoot项目升级Swagger3.0后，swagger-ui.html 404？别慌，5分钟搞定新版访问路径和依赖配置
SpringBoot项目升级Swagger3.0后访问路径失效的深度解决方案
最近在将SpringBoot项目中的Swagger从2.x版本升级到3.0时，不少开发者遇到了一个令人困惑的问题：按照旧版教程配置后，访问/swagger-ui.html却返回404错误。这实际上是Swagger3.0版本中的一个重大变更，本文将深入剖析问题根源，并提供一套完整的解决方案。
1. 问题现象与原因分析
当你满怀期待地输入http://localhost:8080/swagger-ui.html，却只看到一个冷冰冰的404页面时，先别急着怀疑人生。这不是你的配置出了问题，而是Swagger3.0对UI访问路径做了重大调整。
在Swagger2.x版本中，UI界面的默认访问路径确实是/swagger-ui.html。但在3.0版本中，开发团队对这个路径进行了标准化调整，改为了/swagger-ui/index.html。这个变更背后的考虑主要有两点：
- 标准化：与大多数现代Web应用的静态资源路径规范保持一致
- 安全性：避免直接暴露HTML文件，增加一层目录结构
同时，依赖配置也发生了显著变化。在Swagger2.x时代，我们需要分别引入两个依赖：
<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>而在3.0版本中，SpringFox团队推出了一个全新的starter依赖，将这两个功能整合在了一起：
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency>2. 完整解决方案
2.1 依赖配置调整
首先，我们需要彻底移除旧版的依赖配置。在pom.xml或build.gradle中，删除以下内容：
<!-- 删除这两个依赖 --> <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>然后，添加新的starter依赖：
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency>注意：确保你的SpringBoot版本与Swagger3.0兼容。推荐使用SpringBoot 2.4.x或更高版本。
2.2 主程序配置变更
在SpringBoot的主启动类上，我们需要将@EnableSwagger2注解替换为@EnableOpenApi：
@SpringBootApplication @EnableOpenApi // 替换原来的@EnableSwagger2 public class Application { public static void main(String[] args) { SpringApplication.run(Application.class, args); } }2.3 访问路径调整
完成上述配置后，正确的访问路径应该是：
http://localhost:8080/swagger-ui/index.html如果你仍然习惯使用/swagger-ui.html，可以通过添加一个简单的重定向配置来实现：
@Configuration public class SwaggerUiRedirectConfig implements WebMvcConfigurer { @Override public void addViewControllers(ViewControllerRegistry registry) { registry.addRedirectViewController("/swagger-ui.html", "/swagger-ui/index.html"); } }3. 高级配置与自定义
3.1 基础信息配置
Swagger3.0仍然支持对API文档的基础信息进行自定义配置：
@Configuration public class SwaggerConfig { @Bean public OpenAPI customOpenAPI() { return new OpenAPI() .info(new Info() .title("API文档") .version("1.0") .description("项目API文档") .contact(new Contact() .name("开发团队") .url("http://example.com") .email("contact@example.com")) .license(new License() .name("Apache 2.0") .url("http://springdoc.org"))); } }3.2 分组配置
如果你的项目中有多个API模块，可以为它们创建不同的分组：
@Bean public GroupedOpenApi publicApi() { return GroupedOpenApi.builder() .group("public-api") .pathsToMatch("/public/**") .build(); } @Bean public GroupedOpenApi adminApi() { return GroupedOpenApi.builder() .group("admin-api") .pathsToMatch("/admin/**") .build(); }3.3 安全配置
如果API需要认证，可以添加安全配置：
@Bean public OpenAPI customOpenAPI() { return new OpenAPI() .addSecurityItem(new SecurityRequirement().addList("bearerAuth")) .components(new Components() .addSecuritySchemes("bearerAuth", new SecurityScheme() .name("bearerAuth") .type(SecurityScheme.Type.HTTP) .scheme("bearer") .bearerFormat("JWT"))); }4. 常见问题排查
4.1 仍然出现404错误
如果按照上述步骤配置后仍然无法访问，可以检查以下几点：
- 依赖冲突：运行
mvn dependency:tree查看是否有冲突的依赖 - 路径拦截：检查是否有拦截器或过滤器拦截了
/swagger-ui/**路径 - 静态资源：确保没有自定义的静态资源处理覆盖了默认配置
4.2 注解不生效
如果@EnableOpenApi注解报错或不起作用，可能是以下原因：
- 依赖未正确引入：确认
springfox-boot-starter依赖已正确添加 - 版本不兼容：检查SpringBoot和Swagger版本是否匹配
- 缓存问题：尝试清理IDE缓存并重新构建项目
4.3 界面加载缓慢
Swagger UI加载缓慢可能是由于：
- API数量过多：考虑使用分组功能分割文档
- 网络问题：检查CDN资源是否可访问
- 浏览器缓存：尝试清除浏览器缓存或使用无痕模式
5. 最佳实践与建议
在实际项目中使用Swagger3.0时，我有几点经验分享：
- 版本管理：在大型项目中，建议固定Swagger版本，避免自动升级带来的意外问题
- 生产环境：生产环境建议关闭Swagger UI，或通过权限控制访问
- 文档补充：虽然Swagger可以自动生成API文档，但重要的业务说明仍需手动补充
- 性能监控：定期检查Swagger对应用性能的影响，特别是API数量很多时
// 生产环境关闭Swagger的配置示例 @Profile("!prod") @Configuration @EnableOpenApi public class SwaggerConfig { // 配置内容 }Swagger3.0带来的这些变化虽然初期可能造成一些困扰，但从长远来看，这些改进使得API文档工具更加标准化和现代化。经过这次升级，你会发现新的UI界面更加美观，功能也更加完善。