Debian Swagger 如何进行错误排查

Debian 上 Swagger 错误排查清单

一 快速定位问题范围

• 明确运行形态：是 Node.js + swagger-jsdoc/swagger-ui-express、Java/Spring Boot（springfox/swagger-ui）、还是 .NET Core + Swashbuckle、或 Docker/K8s 部署的 Swagger UI。
• 明确访问路径：Swagger UI 通常位于 http://://swagger-ui.html 或 /swagger-ui/；后端 OpenAPI JSON 通常为 /v2/api-docs 或 /v3/api-docs。先直接 curl 验证后端 JSON 是否可达。
• 明确错误现象：页面空白、控制台报错、接口 404/500、JSON 解析失败、注解不生效等，分别对应前端资源、后端生成、路由或权限问题。

二 系统与服务层排查

• 查看服务状态与端口：确认进程存活与端口监听，例如：
  • 查看进程：ps aux | grep swagger
  • 监听端口：ss -ltnp | grep : 或 netstat -tulpen | grep
• 实时日志与内核/系统日志：
  • 应用日志：tail -f /var/log/your-app.log 或 journalctl -u your-service -f
  • 系统日志：tail -f /var/log/syslog；内核日志：dmesg
• 资源与网络：
  • 资源：top/htop 观察 CPU/内存/IO
  • 连通：ping、curl -I http://127.0.0.1:/health
  • 防火墙/安全组：确认 iptables/firewalld 或云安全组已放行对应端口
• 依赖与更新：
  • 系统包：sudo apt update && sudo apt upgrade
  • 修复依赖：sudo apt install -f
  • 如为 Node 项目：sudo npm update；必要时重装相关包

三 应用与配置层排查

• 配置与规范文件：
  • 校验 swagger.yaml/swagger.json 语法与引用路径（可使用在线或 CLI 校验器）
  • 检查路径、模型、标签、服务器地址等是否与实际服务一致
• 注解与版本兼容：
  • Spring Boot 项目核对 springfox/swagger 与 Spring Boot 版本匹配；Spring Boot 3.x 与部分旧版 Swagger 存在兼容性问题，需选用适配版本或迁移至 springdoc-openapi
  • 排查依赖冲突（如 Maven/Gradle 依赖树），避免版本不一致
• 路由与安全：
  • 确认 /swagger-ui.html、/v2/api-docs、/v3/api-docs 等端点未被 Spring Security/Shiro/Nginx 拦截或鉴权误拦
  • 反向代理（Nginx）正确代理静态资源与 API 路径，避免路径重写错误
• 容器与权限：
  • Docker：确认容器对配置/静态资源有读权限，端口映射正确，环境变量（如 SPRING_PROFILES_ACTIVE）设置无误
  • 文件权限：工作目录与日志目录可被运行用户读写

四 常见症状与处理对照表

五 验证与监控

• 可用性自检脚本：
  • 检查 UI：curl -f http://127.0.0.1:/swagger-ui.html || echo FAIL
  • 检查 JSON：curl -f http://127.0.0.1:/v3/api-docs | head -n 20
• Spring Boot Actuator（如集成）：
  • 健康检查：http://:/actuator/health
  • 指标：http://:/actuator/metrics
• 运行监控：
  • 系统：top/htop、ss -ltnp
  • 容器：docker stats
  • 日志持续观察：tail -f /var/log/your-app.log、journalctl -u your-service -f