debian swagger如何调试

在 Debian 上“调试 Swagger”通常指下面几类场景之一，我先按常见情况给你一个清晰路线，你可以对照你的情况选择：

一、你指的是哪种 Swagger？

1️⃣ Swagger UI（前端页面打不开 / 报错）

• 通过 Nginx / Apache 部署
• Docker 部署
• Spring Boot 内嵌 Swagger

2️⃣ Swagger 注解不生效（接口没显示）

• Springfox / springdoc-openapi
• Go / Node / Python 后端

3️⃣ Swagger JSON 报错（/v2/api-docs 或 /v3/api-docs）

• 401 / 403
• 500 错误
• 字段缺失

二、通用调试步骤（强烈推荐）

✅ 1. 直接访问 Swagger JSON

curl http://localhost:8080/v2/api-docs
# 或
curl http://localhost:8080/v3/api-docs

如果这里就报错，问题在后端，不是 UI。

✅ 2. 查看后端日志（最重要）

journalctl -u your-service -f
# 或
docker logs -f container_name

常见错误：

• No mapping for GET /v2/api-docs
• Failed to load API definition
• NullPointerException in ModelConverters

✅ 3. 浏览器开发者工具

打开 Swagger UI → F12 → Network：

• 看请求 /v2/api-docs 状态码
• 看 Response 是否是合法 JSON

三、Debian + Nginx 常见坑

❌ 现象：Swagger UI 白屏

原因：静态资源 404

location /swagger-ui/ {
    proxy_pass http://localhost:8080/;
}

✅ 正确示例（Spring Boot）：

location /swagger-ui.html {
    proxy_pass http://localhost:8080;
}

location /swagger-resources/ {
    proxy_pass http://localhost:8080;
}

location /v2/api-docs {
    proxy_pass http://localhost:8080;
}

location /webjars/ {
    proxy_pass http://localhost:8080;
}

四、Spring Boot 常见调试点

✅ 是否引入依赖

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
</dependency>
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger-ui</artifactId>
</dependency>

或（推荐）：

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

✅ 是否启用

@EnableSwagger2
@Configuration
public class SwaggerConfig {}

springdoc 不需要这个。

五、权限 / Security 拦截

如果你用了 Spring Security：

.antMatchers(
  "/swagger-ui.html",
  "/swagger-resources/**",
  "/v2/api-docs",
  "/webjars/**"
).permitAll()

六、快速自查清单 ✅

• [ ] 能 curl 到 api-docs
• [ ] 后端无异常日志
• [ ] Nginx 没拦截静态资源
• [ ] Security 已放行
• [ ] 依赖版本匹配

七、如果你愿意，我可以直接帮你定位

你可以直接贴：

1. 后端语言 / 框架
2. Swagger 版本
3. 报错截图或日志
4. 部署方式（Docker / Nginx / 本地）

我可以一步一步帮你调。