怎样调试linux swagger

在 Linux 下“调试 Swagger”通常指下面几种场景之一，我先按最常见情况给你一个清晰路径，你再对照自己的情况：

一、你用的是哪种 Swagger？

先确认你是哪一种：

Swagger UI（前端页面）
Swagger Editor
Spring Boot + springdoc / swagger-ui
Node.js / Python 等后端生成 Swagger
Swagger 文档（OpenAPI YAML/JSON）写错

二、通用调试思路（最重要）

1️⃣ 先看 Swagger JSON 是否正常

Swagger UI 本质只是渲染一个 JSON：

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

或：

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

✅ 如果 JSON 报错 → 问题在后端
✅ 如果 JSON 正常但页面异常 → 问题在前端

三、常见场景调试方法

✅ 场景 1：Spring Boot + Swagger

依赖

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

访问地址

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

调试方法

# 看日志
tail -f logs/application.log

# 看端口
netstat -tunlp | grep 8080

常见问题

被 Spring Security 拦截

@Bean
public SecurityFilterChain filterChain(HttpSecurity http) {
    http.authorizeHttpRequests()
        .requestMatchers("/swagger-ui/**", "/v3/api-docs/**").permitAll();
}

✅ 场景 2：Swagger UI 打不开（空白页）

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

检查：

是否 404
是否被 Nginx / 网关拦截
是否跨域（CORS）

✅ 场景 3：Swagger JSON 写错（YAML/JSON）

用命令行校验：

npm install -g @apidevtools/swagger-cli
swagger-cli validate swagger.yaml

或在线：

https://editor.swagger.io

✅ 场景 4：接口能调但 Swagger 不显示

常见问题：

Controller 没有 @RestController
方法没有 @RequestMapping
DTO 循环引用
泛型不支持

开启 debug：

logging:
  level:
    org.springdoc: DEBUG

四、Linux 常用调试命令汇总

# 看端口
ss -tunlp | grep 8080

# 看进程
ps -ef | grep java

# 抓 HTTP 请求
tcpdump -i lo port 8080

# 测试接口
curl -X GET http://localhost:8080/v3/api-docs

五、你可以直接告诉我

你可以直接回复下面任意一条，我可以给你精确到命令级的方案：

你用的是 什么语言 / 框架
报错信息（截图或文本）
Swagger 打不开还是接口不对
是否在 Docker / Nginx / K8s 中

我可以一步一步帮你排。