Swagger UI加载失败：JSON正常加载但JS、CSS文件存在问题

我之前也碰到过一模一样的问题！JSON能正常拉取但Swagger UI的样式和交互全挂了，折腾了好一阵才搞定，给你分享几个最可能的解决方向：

• 检查Swagger UI资源的路径配置
  很多时候是资源引用路径出错了。比如用Spring Boot集成Swagger时，要确认swagger-ui.html里引用的swagger-ui-bundle.js、swagger-ui.css这些文件的路径是否正确。如果是手动引入静态资源，得确保文件放在了项目的静态资源目录（比如src/main/resources/static或public）里，服务器能正确映射到这些资源。
  举个例子，要是Swagger UI资源放在/swagger-ui/目录下，页面里的引用应该是<script src="/swagger-ui/swagger-ui-bundle.js"></script>，别用相对路径导致找不到资源。

• 排查CORS跨域问题
  如果API和Swagger UI不在同一个域名下，浏览器可能会因为CORS策略阻止加载JS/CSS资源。打开浏览器开发者工具（F12）切换到Network标签，刷新页面看看那些JS/CSS文件的请求状态是不是403或者报错。如果是，要么在服务器端配置CORS允许Swagger UI所在域名访问，要么直接把Swagger UI部署到和API同域名下。

• 确认Swagger UI与OpenAPI版本的兼容性
  不同版本的Swagger UI对OpenAPI版本有要求：比如Swagger UI 3.x支持OpenAPI 3.0，老版本可能只支持Swagger 2.0（也就是OpenAPI 2.0）。要是你的JSON是OpenAPI 3.0格式，但用了旧版Swagger UI，就可能出现资源加载异常或渲染失败。建议升级到对应版本的Swagger UI，比如用最新3.x版本适配OpenAPI 3.x的JSON。

• 清理浏览器缓存或用隐身模式测试
  有时候浏览器缓存了旧的、损坏的JS/CSS文件，导致新资源无法正常加载。试试按Ctrl+Shift+R强制刷新页面，或者打开隐身窗口访问Swagger UI，排查是不是缓存的锅。

• 检查服务器静态资源配置
  如果是自己搭建的服务器（比如Node.js、Nginx），要确保服务器正确处理静态资源请求。比如Nginx要配置root或alias指向Swagger UI的静态文件目录，Node.js的Express要使用express.static()中间件托管静态资源。服务器配置不对的话，JS/CSS文件会返回404，自然加载失败。

• 查看浏览器控制台的错误信息
  最后一定要看浏览器控制台（F12的Console标签）的报错，里面会明确告诉你哪个资源加载失败、是什么错误（比如404、500、跨域）。根据错误信息针对性解决比瞎试效率高多了！比如显示Failed to load resource: the server responded with a status of 404 (Not Found)，那直接修正资源路径就行。

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