Swagger在Linux系统中的故障排查指南
swagger-ui.html或/swagger端点时出现404 Not Found、连接被拒绝或页面空白。ps aux | grep "swagger"（Java项目）或systemctl status your-swagger-service确认服务是否启动；若未启动，使用systemctl start your-swagger-service启动服务。netstat -tulnp | grep <swagger-port>（如8080）或ss -lntp | grep <port>检查应用是否在正确端口监听；若未监听，检查应用配置（如Spring Boot的server.port）。sudo ufw status查看防火墙规则，若端口未开放，执行sudo ufw allow <port>/tcp；若使用云服务器，还需检查安全组规则是否允许入站流量。application.properties或application.yml中的spring.resources.static-locations是否包含Swagger UI的静态资源路径（如classpath:/META-INF/resources/）；若使用Nginx代理，需配置location块指向正确路径（如proxy_pass http://localhost:5000;）。@Api注解（Swagger 2），方法有@ApiOperation注解；模型类有@ApiModel和@ApiModelProperty注解（如Java项目）。mvn dependency:tree | grep swagger（Maven）或npm list swagger（Node.js）查看依赖版本；确保Swagger核心库（如springfox-swagger2）与UI库（如springfox-swagger-ui）版本一致，且与框架（如Spring Boot）版本兼容（如Spring Boot 2.7.x适配springfox-swagger2 2.9.2）。pathMapping（如Spring Boot的Docket配置.pathMapping("/api-docs")），确保与访问URL一致；使用curl -v http://localhost:<port>/swagger.json验证JSON文件是否能正常获取。WebMvcConfigurer Bean（如@Bean public WebMvcConfigurer corsConfigurer() { return new WebMvcConfigurer() { @Override public void addCorsMappings(CorsRegistry registry) { registry.addMapping("/**").allowedOrigins("*").allowedMethods("*"); } }; }）；或在Swagger配置中添加@CrossOrigin注解。add_header 'Access-Control-Allow-Origin' '*';和add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS';到location块。Docket配置securitySchemes（如apiKey）和securityContexts（如anyRequest().authenticated()）；例如：@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.securitySchemes(Arrays.asList(apiKey()))
.securityContexts(Arrays.asList(securityContext()))
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
private ApiKey apiKey() { return new ApiKey("Bearer", "Authorization", "header"); }
private SecurityContext securityContext() { return SecurityContext.builder().securityReferences(defaultAuth()).build(); }
private List<SecurityReference> defaultAuth() { return Arrays.asList(new SecurityReference("Bearer", new AuthorizationScope[0])); }
Authorization头）。NoSuchMethodError、ClassNotFoundException），或Swagger UI无法加载。mvn dependency:tree（Maven）或gradle dependencies（Gradle）查看依赖冲突；重点检查springfox-swagger2、springfox-swagger-ui与其他库（如spring-boot-starter-web）的版本兼容性。pom.xml中使用<exclusions>排除冲突的依赖（如<exclusion><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-tomcat</artifactId></exclusion>），或升级到兼容版本。journalctl -u your-service-name -f（Systemd服务）或tail -f /var/log/spring-boot-app.log（Spring Boot默认日志路径）实时查看日志；通过grep -i "swagger"过滤Swagger相关日志，定位具体错误（如NullPointerException、ConfigurationException）。application.properties中添加logging.level.io.swagger=DEBUG，或在启动命令中添加--debug参数，获取更详细的日志信息。curl -v http://localhost:<port>/api-endpoint测试API是否能正常响应；若curl成功但Swagger无法访问，可能是前端配置问题。ping your-server-ip测试服务器可达性；使用traceroute your-server-ip检查网络路由是否正常。npx swagger-cli validate swagger.json（本地安装）或docker run --rm -v $(pwd):/tmp openapitools/openapi-generator-cli validate -i /tmp/swagger.yaml（Docker）验证Swagger JSON/YAML文件的合法性；修复语法错误（如缺少paths字段、格式错误）。docker pull swaggerapi/swagger-editor运行本地Swagger Editor，导入Swagger文档进行在线验证，快速定位规范问题。swagger-cli validate命令添加到CI/CD流水线（如Jenkins），在代码提交时自动验证Swagger文档，避免不规范文档上线。cp swagger.json swagger-$(date +%Y%m%d).json），防止文档丢失或损坏。
