centos swagger故障排除

CentOS 上 Swagger 故障排查清单

一快速定位路径

确认访问入口：Spring Boot 集成常用路径为 http://:<端口>/swagger-ui.html；若使用 Springfox Swagger2，后端 JSON 通常为 /v2/api-docs；静态资源在 /webjars/。Nginx 反向代理或上下文路径变更时，这些路径容易 404 或白屏。
先看应用日志与控制台报错，再核对网络连通与防火墙策略，最后检查代理转发与静态资源配置。

二常见症状与修复要点

页面 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();
    }
}

如使用上下文路径（如 /api），在 application.properties 增加：
springfox.documentation.swagger-ui.base-path=/api
依赖示例（Maven，Springfox Swagger2）：
io.springfox:springfox-swagger2:2.9.2
io.springfox:springfox-swagger-ui:2.9.2

五一键自检命令清单

后端直连测试：
curl -I http://127.0.0.1:8080/v2/api-docs
curl -I http://127.0.0.1:8080/swagger-ui.html
防火墙放行（示例端口 8080）：
sudo firewall-cmd --zone=public --add-port=8080/tcp --permanent && sudo firewall-cmd --reload
外部访问测试：
curl -I http://<服务器IP>:8080/swagger-ui.html
查看应用日志：
journalctl -u your-app.service -f
Nginx 重载：
sudo nginx -s reload
浏览器开发者工具：检查 Network 中 /v2/api-docs 与静态资源是否 200，响应内容是否为合法 JSON。

最新问答

相关标签