swag init 生成的 swagger.json 中 paths 为空，是因为 handler 函数缺少紧贴声明的 // @summary 和 // @router 注释，且函数必须首字母大写、位于非忽略文件中，否则不会被扫描。
swag init 生成的 docs/swagger.json 里 paths 为空，不是路径写错了，而是 handler 函数根本没被扫描到 —— 它只认带 // @Summary 的具名函数，且注释必须紧贴函数声明。
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"（注意是path，类型写int而非string） -
c.Query("page")→// @Param page query int false "页码" default(1) -
c.ShouldBindJSON(&req)→// @Param req body models.User true "请求体"，且models.User必须是可导出 struct，字段带json:tag - 别用
map[string]interface{}做 body 输入，swag 解析不了，文档里只会显示object
启动报 panic: no required "doc" found？docs 包根本没加载
这个 panic 不是 swagger.json 缺失，而是 Gin 启动时找不到 docs.SwaggerInfo 变量 —— 说明生成的 docs 包压根没被 import。
- 确保在
main.go（或启动文件）顶部写了：import _ "your-module-name/docs"（注意下划线导入） -
swag init -g main.go必须在 module 根目录执行，否则生成的docs/docs.go里SwaggerInfo初始化代码可能为空或路径错误 - 检查
docs/docs.go是否真实存在、是否含var SwaggerInfo = ...，如果为空，说明全局注释（如// @title）漏了或格式有硬伤 - 注册路由时必须用
ginSwagger.WrapHandler(docs.Handler)，不是docs.Handler()（后者是调函数，不是传 handler）
Struct 字段不进 Response Model？导出 + tag + 可见性三者缺一不可
Swagger 的 model 是从 struct 定义推导的，但 Go 的字段可见性规则比 JSON 序列化更严：即使字段打了 json:"user_id"，只要首字母小写，swag 就当它不存在。
- 结构体名、字段名都必须首字母大写（导出）
- 每个字段必须有
json:tag，且值非空（如json:"user_id"，不能是json:"-"） - 嵌套 struct 也要满足上述条件，否则链路中断，子字段不会展开
- 如果结构体在其他 module，需在 main.go 顶部加
// @modelsPackage github.com/yourname/project/models
最容易被忽略的是注释和函数的物理距离 —— 看似写了 // @Summary，但中间夹了个空行或注释块，swag 就认为它不属于那个函数。生成前用 swag init -v 开启详细日志，能快速定位哪几个函数被跳过了。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
