怎么调试linux swagger

在 Linux 上“调试 Swagger”通常分几种场景：

调试 Swagger UI 打不开 / 404
调试 Swagger 生成的接口不对（字段缺失、注解不生效）
调试 后端服务集成 Swagger（Spring / Go / Node 等）
调试 Swagger 文档与代码不一致

下面按常见情况给你一套 Linux 下的调试思路 + 命令。

一、确认 Swagger 服务是否在运行

1. 看端口和进程

# 查看监听端口
ss -lntp | grep 8080
# 或
netstat -lntp | grep 8080

# 看进程
ps -ef | grep swagger
ps -ef | grep java

如果是 Spring Boot：

ps -ef | grep java

二、直接访问 Swagger 接口（最关键）

Swagger UI 常见路径

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

测试：

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

✅ 如果 api-docs 有 JSON → Swagger 正常
❌ 如果 404 → 路由或配置问题

三、Spring Boot + Swagger 调试（最常见）

1. 检查依赖

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

Spring Boot 2.6+ 建议：

Springdoc（推荐）

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

访问：

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

2. 开启 DEBUG 日志

logging:
  level:
    springfox: DEBUG
    io.swagger: DEBUG

或：

-Dlogging.level.springfox=DEBUG

3. 常见问题排查

❌ 404 但接口存在

@Configuration
@EnableSwagger2
public class SwaggerConfig {}

Spring Boot 2.6+ 加：

@Bean
public WebMvcConfigurer webMvcConfigurer() {
    return new WebMvcConfigurer() {
        @Override
        public void addResourceHandlers(ResourceHandlerRegistry registry) {
            registry.addResourceHandler("/swagger-ui/**")
                    .addResourceLocations("classpath:/META-INF/resources/");
        }
    };
}

四、Go / Gin + Swagger 调试

1. 生成 docs

swag init

2. 确认路由

r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))

3. 测试

curl http://localhost:8080/swagger/doc.json

五、用浏览器远程调试（Linux 无界面）

1. 端口转发

ssh -L 8080:localhost:8080 user@server

本地浏览器访问：

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

六、Swagger 注解不生效（字段不显示）

Java 常见原因

没加 @ApiModelProperty
用了 private 但无 getter
Lombok 没生效

@ApiModelProperty("用户名")
private String username;

JSON 为空

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

七、快速自检清单 ✅

[ ] 服务端口通
[ ] /v2/api-docs 或 /v3/api-docs 有数据
[ ] Swagger UI 路径正确
[ ] DEBUG 日志已开
[ ] 注解和路由都正确

如果你能告诉我：

用的什么语言（Java / Go / Node）
什么框架（Spring Boot / Gin / Express）
具体现象（404 / 空白 / 字段缺失）

我可以直接给你针对性调试步骤。