Linux下Swagger怎么调试

在 Linux 下调试 Swagger（通常指 Swagger UI / OpenAPI），常见场景有几种，我按最常用 → 进阶给你系统讲一下，基本都能覆盖 90% 的需求。

一、最常见：Swagger UI 接口调不通（本地 / 服务器）

1️⃣ 确认 Swagger 是否正常启动

浏览器访问：

http://localhost:8080/swagger-ui.html
# 或
http://localhost:8080/swagger-ui/index.html

如果打不开：

curl http://localhost:8080/swagger-ui.html

✅ 能返回 HTML → 服务正常
❌ 连接拒绝 → 服务没启动或端口不对

2️⃣ 查看 Swagger JSON 是否生成成功

Swagger UI 本质读取的是 OpenAPI JSON：

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

或：

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

如果返回 JSON，说明 后端 OK
如果 404 → 配置问题

二、Swagger 接口调用失败（重点）

1️⃣ 打开浏览器开发者工具（F12）

重点看：

Network（网络）
Console（控制台）

常见错误：

现象	原因
403	权限 / Spring Security
401	未登录 / Token
404	路径不匹配
500	后端异常
CORS 报错	跨域问题

2️⃣ 直接 curl 调试接口（Linux 必备）

Swagger UI 点“Try it out”本质就是发 HTTP 请求。

curl -X GET "http://localhost:8080/api/user/1" \
  -H "accept: application/json"

带 Token：

curl -X GET "http://localhost:8080/api/user/1" \
  -H "Authorization: Bearer xxx"

✅ 能通 → Swagger UI 配置问题
❌ 不通 → 后端问题

三、Spring Boot + Swagger 常见调试点（Linux 环境）

1️⃣ 检查依赖

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

或老版本：

springfox-boot-starter

2️⃣ 检查是否被拦截（Spring Security）

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

3️⃣ 检查端口 & 环境

netstat -tunlp | grep 8080
# 或
ss -tunlp | grep 8080

确认：

服务监听的是 0.0.0.0 还是 127.0.0.1
是否被 Docker / 防火墙拦截

四、Docker + Linux 场景

1️⃣ 容器里访问 Swagger

docker ps
docker exec -it 容器id sh
curl http://localhost:8080/swagger-ui.html

2️⃣ 宿主机访问容器

http://宿主机IP:映射端口/swagger-ui.html

五、Swagger UI 本身调试技巧

1️⃣ 修改 Swagger 配置（显示更多错误）

@Bean
public OpenAPI customOpenAPI() {
    return new OpenAPI()
        .info(new Info().title("API").version("1.0"));
}

2️⃣ 打开 Swagger UI 的详细错误

浏览器 Network → 查看 Response 内容

六、快速定位问题 checklist ✅

✅ 服务是否启动
✅ /v3/api-docs 是否返回 JSON
✅ 是否被 Spring Security 拦截
✅ 是否跨域（CORS）
✅ 端口 / Docker / 防火墙
✅ curl 能否直接调通接口

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

你可以直接贴：

后端框架（Spring Boot / Node / Python）
Swagger 版本
具体报错信息或截图
是本地还是服务器 / Docker

我可以一步一步帮你把问题定位到“哪一行配置”。