linux swagger报错怎么查

在 Linux 上排查 Swagger 报错，可以按下面思路一步步来，先定位是「起不来」「访问不了」还是「接口文档异常」。

一、先确认 Swagger 类型

不同技术栈排查方式不同：

• Spring Boot + Swagger / SpringDoc
• Node.js（Express + swagger-ui-express）
• Python（FastAPI / Flask + swagger）
• Nginx 反向代理后的 Swagger

你可以先告诉我用的是哪种。

二、通用排查步骤（必做）

1️⃣ 看服务是否启动

ps -ef | grep java
# 或
ps -ef | grep node

端口是否监听：

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

2️⃣ 本地直接访问（绕过 Nginx）

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

• 能访问 → 问题在 Nginx / 防火墙
• 不能访问 → 问题在 应用本身

3️⃣ 查看日志（最重要）

Spring Boot

tail -f logs/application.log

常见错误：

• Failed to start bean 'documentationPluginsBootstrapper'
• `No qualifying bean of type ‘org.springframework.web.servlet.’
• Swagger 版本与 Spring Boot 不兼容

Node

journalctl -u your-node-service
# 或直接看启动终端输出

三、常见 Swagger 报错 & 解决

✅ Spring Boot 常见坑

1. Spring Boot 2.6+ 与 Swagger 冲突

spring:
  mvc:
    pathmatch:
      matching-strategy: ANT_PATH_MATCHER

2. SpringDoc 推荐配置

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

访问：

/swagger-ui/index.html

✅ Nginx 导致 Swagger 打不开

需要放行：

location /swagger-ui/ {
    proxy_pass http://backend/;
}
location /v3/api-docs/ {
    proxy_pass http://backend/;
}

✅ 防火墙问题

firewall-cmd --list-all
firewall-cmd --add-port=8080/tcp --permanent
firewall-cmd --reload

四、你可以这样给我信息，我直接帮你定位

请把下面信息贴出来：

1. 用的什么技术（Spring Boot？Node？）
2. 报错截图或日志
3. 访问地址
4. 是否用 Nginx

我可以直接帮你定位到具体原因 ✅