Go Gin项目Swagger文档生成：从“空路径”到完整可用的排查指南

遇到 swag init 生成的 docs/swagger.json 里 paths 为空，先别急着怀疑路由路径写错了。问题的根源往往更直接：你的 handler 函数根本没被扫描工具识别到。记住一个核心原则：swag 只认那些带有特定“身份证”——即紧贴函数声明的 // @Summary 和 // @Router 注释——的具名导出函数。

swag init 找不到接口？先看 handler 函数有没有“身份证”

swag 工具的工作原理是静态分析源码，它不会去解析 router.GET() 这类在运行时才注册的路由。它扫描的是 Go 源文件中那些带有 Swagger 注释的函数定义。没有注释，就等于没有接口。

• 注释是硬性要求：// @Summary 和 // @Router 两者缺一不可。漏掉任何一个，该接口都不会出现在最终的 swagger.json 的 "paths" 对象里。
• 注释位置必须紧贴：注释必须写在 handler 函数定义的正上方，中间不能有空行，也不能写在 func main() 里，更不能用匿名函数或闭包。
• 函数名必须导出：函数名首字母必须大写，否则 swag 解析器会直接跳过。
• 注意文件排除规则：别把 handler 放在 _test.go、mock_*.go 或者被 //go:build ignore 标记的文件里，因为 swag 默认会忽略这些文件。

参数不显示？@Param 写法和 Gin 实际取值方式要对得上

Gin 框架里的 c.Param("id") 和 c.Query("page") 并不会自动映射成 Swagger 文档中的参数，这全靠 // @Param 注释手动声明。一旦写错参数类型或位置，文档里对应的参数就会“消失”。

• 路径参数：对应 c.Param("id")，应写为 // @Param id path int true "用户ID"。这里的关键是类型写 int 而非 string，位置是 path。
• 查询参数：对应 c.Query("page")，应写为 // @Param page query int false "页码" default(1)。
• 请求体：对应 c.ShouldBindJSON(&req)，应写为 // @Param req body models.User true "请求体"。同时，models.User 必须是可导出的结构体，且字段带有正确的 json: 标签。
• 避免使用模糊类型：别用 map[string]interface{} 作为请求体，swag 无法解析这种动态结构，文档里只会显示一个笼统的 object。

启动报 panic: no required "doc" found？docs 包根本没加载

这个 panic 错误通常不是因为 swagger.json 文件缺失，而是 Gin 服务启动时找不到 docs.SwaggerInfo 这个变量——这直接说明生成的 docs 包压根没有被导入。

立即学习“go语言免费学习笔记（深入）”；

• 确保正确导入：在 main.go（或你的应用启动文件）顶部，必须写下：import _ "your-module-name/docs"（注意这里是下划线导入）。
• 在正确目录执行命令：swag init -g main.go 必须在 Go module 的根目录下执行。否则，生成的 docs/docs.go 文件里的 SwaggerInfo 初始化代码可能为空或路径错误。
• 检查生成文件：确认 docs/docs.go 文件真实存在，并且包含 var SwaggerInfo = ... 的初始化代码。如果文件内容为空，很可能是项目顶层的全局注释（如 // @title）漏写了或者格式有误。
• 正确注册路由：注册 Swagger 路由时，应该使用 ginSwagger.WrapHandler(docs.Handler)，而不是 docs.Handler()（后者是调用函数，而非传递 handler）。

Struct 字段不进 Response Model？导出 + tag + 可见性三者缺一不可

Swagger 的响应模型是从你的 Go struct 定义推导出来的，但这里有个陷阱：Go 语言的字段可见性规则比 JSON 序列化更严格。即使一个字段打了 json:"user_id" 标签，只要它的首字母是小写（未导出），swag 工具就会当它不存在。

• 结构体和字段都必须导出：结构体名、以及你希望出现在文档里的每一个字段名，首字母都必须大写。
• 字段标签不可或缺：每个字段都必须有 json: 标签，并且标签值不能为空或忽略标记（例如应该是 json:"user_id"，而不能是 json:"-"）。
• 注意嵌套结构：如果结构体中嵌套了其他结构体，被嵌套的结构体也必须满足上述“导出+标签”的条件，否则字段链会中断，子字段不会被展开。
• 跨模块引用：如果响应模型的结构体定义在其他 module，需要在 main.go 顶部添加注释：// @modelsPackage github.com/yourname/project/models。

最后，一个最容易被忽略的细节是注释和函数之间的物理距离。有时候，明明写了 // @Summary，但因为中间不小心多了一个空行，或者被其他注释块隔开，swag 就会认为这条注释不属于下面的函数。一个高效的排查方法是：在生成文档前，使用 swag init -v 命令开启详细日志模式，它能帮你快速定位具体是哪些函数被扫描工具跳过了。