症状：访问Swagger UI页面时出现404（页面不存在）、503（服务不可用）或连接被拒绝错误。
解决方法：
systemctl status your-swagger-service（如Spring Boot应用为systemctl status your-spring-boot-app）确认服务是否启动；若未启动，用systemctl start your-swagger-service启动服务。netstat -tulnp | grep <swagger-port>（如8080、3000）检查Swagger服务是否在目标端口监听；若未监听，需检查应用配置（如application.properties中的server.port）。sudo firewall-cmd --zone=public --add-port=<port>/tcp --permanent并sudo firewall-cmd --reload开放端口；若使用SELinux，可临时设置为宽松模式setenforce 0（测试后根据需求调整），或通过semanage port -a -t http_port_t -p tcp <port>添加端口规则。location /swagger-ui.html块中包含proxy_pass http://localhost:<app-port>;及必要的请求头转发，如X-Forwarded-For、X-Forwarded-Proto）。症状：Swagger UI页面提示“Failed to load API definition”，或JSON/YAML文件无法加载。
解决方法：
curl -v http://localhost:<port>/swagger.json（或/v3/api-docs，取决于Swagger版本）检查文档是否存在；若返回404，需检查应用配置（如Spring Boot中@EnableSwagger2注解的路径设置）。python -m json.tool swagger.json（JSON文件）或yamllint swagger.yaml（YAML文件）验证文件语法是否正确；若格式错误，需修复应用生成的文档内容。@CrossOrigin注解或全局CORS配置）；若使用Node.js代理，添加const cors = require('cors'); app.use(cors());。症状：修改后端API（如新增接口、修改参数）后，Swagger UI上的文档未同步更新。
解决方法：
/swagger-resources/configuration/ui），强制更新文档缓存。systemctl restart your-spring-boot-app）或Swagger服务，确保最新文档生成。@ApiOperation、@ApiParam等注解正确填写（如value、notes字段），缺失或错误会导致文档不更新。症状：启动时报错（如NoSuchMethodError、ClassNotFoundException），或Swagger UI无法正常渲染。
解决方法：
pom.xml（Maven）或build.gradle（Gradle），更新Swagger相关依赖（如springfox-boot-starter、swagger-ui）至兼容版本，并清理本地仓库后重新构建。症状：访问Swagger UI时提示“Permission denied”（权限不足），或日志中出现“Access Denied”记录。
解决方法：
/opt/swagger-ui/dist）有读取权限，使用chmod -R 755 /opt/swagger-ui修改权限（根据实际路径调整）。setenforce 0临时关闭（测试是否解决问题）；若需永久关闭，编辑/etc/selinux/config将SELINUX=enforcing改为SELINUX=permissive；或通过semanage命令添加访问规则（如semanage fcontext -a -t httpd_sys_content_t "/opt/swagger-ui(/.*)?"）。SecurityConfig中添加静态资源放行（如.antMatchers("/swagger-ui/**", "/v3/api-docs/**").permitAll()）；若使用Nginx，确保location块中没有deny规则。症状：部分接口未显示在Swagger UI中，或参数、响应描述不正确（如返回类型为泛型时无法解析）。
解决方法：
@Api注解（描述模块），方法上有@ApiOperation注解（描述接口功能），参数上有@ApiParam注解（描述参数）；避免注解值为空或包含特殊字符（如反斜线\）。ResponseEntity<List<User>>），在返回类型类（如User）上添加@JsonAutoDetect(fieldVisibility = JsonAutoDetect.Visibility.ANY)注解，确保Swagger能解析泛型信息。/user），通过@ApiOperation的tags属性区分（如tags = "user-management"），防止文档混乱。journalctl -u your-service-name -f（Systemd服务）或tail -f /var/log/your-app.log查看实时日志，过滤“swagger”关键字定位具体错误（如grep -i "swagger" /var/log/your-app.log）。ping <server-ip>测试网络连通性，curl -v http://localhost:<port>/swagger.json验证服务是否可达；若使用域名，检查DNS解析（dig your-domain.com）。