怎么调试Debian的Swagger

调试 Debian 上的 Swagger（通常指 Swagger UI / OpenAPI 接口文档） 时，问题一般集中在 服务启动、接口访问、配置、权限、日志 等方面。下面按常见场景给你一个系统化的排查思路。

一、先明确你用的是哪种 Swagger

在 Debian 上常见情况有：

1. Spring Boot + Swagger / springdoc-openapi
2. Node.js（Express / NestJS）+ swagger-ui-express
3. Python（FastAPI / Flask）+ swagger
4. Nginx 反向代理后的 Swagger
5. 直接部署 Swagger UI 静态页面

不同技术栈调试方式略有差异，但核心思路一致。

二、基础环境检查（通用）

1. 服务是否真的在运行

ps aux | grep swagger
# 或看你对应的服务
systemctl status your-service

2. 端口是否监听

ss -lntp
# 或
netstat -lntp

例如：

LISTEN 0 128 0.0.0.0:8080

3. 本地是否能访问

在 Debian 本机测试：

curl http://localhost:8080/swagger-ui.html
curl http://localhost:8080/v3/api-docs

✅ 能访问 → 服务正常
❌ 不能访问 → 服务或端口问题

三、常见 Swagger 调试场景

✅ 场景 1：Swagger 页面打不开（404 / 空白）

检查点

1. 路径是否正确

   • Spring Boot

     /swagger-ui.html
     /swagger-ui/index.html
     /v3/api-docs
     

   • springdoc-openapi

     /swagger-ui.html
     /v3/api-docs
     

2. 是否被 Spring Security 拦截

@Override
protected void configure(HttpSecurity http) throws Exception {
    http
      .authorizeRequests()
      .antMatchers("/swagger-ui/**", "/v3/api-docs/**").permitAll();
}

3. 是否缺少依赖

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
</dependency>

✅ 场景 2：Swagger 能打开，但接口不显示

常见原因

• Controller 没有被扫描
• 接口没有 @RestController / @RequestMapping
• 使用了 basePackage 配置错误

调试方法

curl http://localhost:8080/v3/api-docs

如果返回 JSON 但接口少：

• 检查 controller 包路径
• 检查是否使用了 Docket / GroupedOpenApi 配置

✅ 场景 3：Debian 上访问 Swagger 很慢 / 超时

排查顺序

1. 防火墙

iptables -L
ufw status

2. Nginx 反向代理问题

location /swagger/ {
    proxy_pass http://127.0.0.1:8080;
}

检查：

• 是否少了 /
• 是否 proxy 了 /v3/api-docs

3. DNS / 网络

ping your-domain.com

✅ 场景 4：Swagger JSON 报错 / 无法解析

典型错误：

Failed to load API definition

调试方法：

curl -I http://localhost:8080/v3/api-docs

检查：

• Content-Type 是否为 application/json
• 是否被拦截器修改了响应

四、日志调试（非常重要）

Spring Boot

tail -f logs/spring.log

开启 debug：

logging:
  level:
    org.springdoc: DEBUG
    springfox: DEBUG

Node.js

node app.js
# 或
pm2 logs

Python FastAPI

uvicorn main:app --reload --log-level debug

五、Debian 特有注意点

1. Java / Node / Python 版本

java -version
node -v
python3 --version

⚠️ 有些 Swagger 版本对 Java 17+ 敏感

2. systemd 服务没输出

journalctl -u your-service -f

3. 权限问题

ls -l /var/log/your-app

避免：

• 端口 < 1024 没权限
• 日志目录不可写

六、快速自检清单 ✅

• [ ] 服务是否运行
• [ ] 端口是否监听
• [ ] 本地 curl 是否成功
• [ ] Swagger JSON 是否正常
• [ ] 是否被 Nginx / 防火墙拦截
• [ ] 日志中有无异常
• [ ] 版本是否兼容

七、如果你愿意，我可以更精确帮你

你可以直接贴出：

1. 你用的 语言 / 框架
2. Swagger 访问 URL
3. 报错截图或日志
4. Debian 版本（cat /etc/os-release）

我可以一步一步帮你定位 ✅