20余个Spring Boot微服务Swagger UI突然全部返回404无法访问问题求助

1. 访问swagger-ui.html返回404的原因 #

• SpringFox 3.x 路径适配问题：你使用的SpringFox 3.0.0版本相比2.x版本调整了静态资源结构，旧版的/swagger-ui.html路径已经废弃，jar包中不存在该文件，你当前的addResourceHandlers配置是适配2.x版本的，对3.x版本无效，3.x的默认Swagger UI访问路径为/swagger-ui/index.html，可以先尝试访问该地址验证。
• 全局拦截规则拦截：如果上述路径仍返回404，大概率是所有服务共用的全局拦截器/过滤器规则被修改，Swagger相关路径（/swagger-ui/**、/webjars/**、/v3/api-docs等）被移出了访问白名单。如果你们的拦截规则支持配置中心热生效，不需要重启服务就能更新规则，完全符合你遇到的故障特征。
• 静态资源映射规则被修改：如果全局公共配置中的spring.web.resources.static-locations参数被调整，会导致SpringBoot无法读取classpath:/META-INF/resources/下的Swagger静态资源，也会返回404。

2. 所有服务同时失效的原因 #

Swagger本身不存在跨服务的全局缓存机制，也不会出现所有服务缓存同时过期的情况。这种未修改、未重启的服务也同步失效的场景，必然是所有服务共享的公共组件、公共配置变更导致的，优先级最高的排查方向是热生效的全局拦截规则、配置中心的公共配置变更。

3. 快速排查步骤 #

1. 先请求默认路径验证核心功能是否正常：

# 验证Swagger UI静态资源是否可访问
curl http://127.0.0.1:11012/swagger-ui/index.html
# 验证Swagger接口生成功能是否正常
curl http://127.0.0.1:11012/v3/api-docs

如果/v3/api-docs能正常返回接口JSON数据，说明Swagger核心功能正常，只是静态资源路径映射有问题。
2. 临时关闭当前服务的所有拦截器、过滤器，再尝试访问Swagger地址，确认是否是拦截规则导致的问题。
3. 登录服务容器检查依赖包完整性：确认服务lib目录下存在springfox-swagger-ui-3.0.0.jar，解压后检查是否存在META-INF/resources/swagger-ui/index.html文件。
4. 查看服务的访问日志，确认/swagger-ui/**的请求被哪个组件拦截后返回了404。

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