CentOS 上 Swagger 故障排查清单
一 快速定位路径
二 常见症状与修复要点
页面 404 或静态资源加载失败：在反向代理（如 Nginx）中，除 /swagger-ui.html 外，还需显式放行 /swagger-resources、/v2/api-docs、/webjars，并正确设置 X-Forwarded-For / X-Forwarded-Proto / X-Forwarded-Host / X-Forwarded-Port，否则 UI 拿不到 JSON 会白屏或报错。
页面白屏或 “Failed to load API definition / Fetch error undefined”：多为代理未转发上述路径、后端未暴露 /v2/api-docs、或浏览器跨域/缓存导致。按上条补齐代理 location，确认后端能直接访问 /v2/api-docs，必要时 Ctrl+F5 强刷或禁用缓存。
访问被拒绝或端口不通：在 CentOS 上放行对应端口（如 firewall-cmd --zone=public --add-port=8080/tcp --permanent && firewall-cmd --reload），或临时关闭防火墙验证是否为策略问题。
Spring Security 拦截：放行 Swagger 相关静态资源与 API 路径，例如对 /swagger-ui.html、/swagger-resources/、/v2/api-docs、/webjars/ 配置 permitAll。
上下文路径或网关前缀导致 404：若应用设置了 server.servlet.context-path 或网关路由前缀，需在 application.properties 中设置 springfox.documentation.swagger-ui.base-path=/你的前缀，确保 UI 能正确请求到 /v2/api-docs。
版本兼容与注解问题：Spring Boot 与 Springfox 版本需匹配；使用 @EnableSwagger2 的 Docket 配置要正确；返回类型建议明确泛型，必要时用 @JsonAutoDetect 调整可见性，避免响应模型字段不显示。
三 Nginx 反向代理示例配置
location /swagger-ui.html {
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Port $server_port;
proxy_pass http://127.0.0.1:8080/swagger-ui.html;
}
location /swagger-resources {
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Port $server_port;
proxy_pass http://127.0.0.1:8080/swagger-resources;
}
location /v2/api-docs {
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Port $server_port;
proxy_pass http://127.0.0.1:8080/v2/api-docs;
}
location /webjars {
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Port $server_port;
proxy_pass http://127.0.0.1:8080/webjars;
}
说明：将 http://127.0.0.1:8080 替换为你的后端服务地址；如使用域名或 HTTPS，确保 X-Forwarded-Proto 与证书配置一致。
四 Spring Boot 最小可用配置示例
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
}
五 一键自检命令清单