Swag的核心价值是通过注释自动生成文档，无需手写YAML或JSON；但需确保注释格式正确、swag init在项目根目录执行、全局注释位于main.go中、swagger路由注册顺序正确、导出字段带json tag、每次修改后重新运行swag init并刷新缓存。
能直接用注释生成文档，不用手写 YAML 或 JSON —— 这是 Swag 的核心价值。但前提是注释格式、工具链和导入顺序都得对，否则 swag init 会静默失败，或 UI 打开后显示 “no API definition found”。
swag init 不生成 docs 目录？检查这三件事
这是最常卡住的一步。不是命令没运行，而是环境或路径不对：
-
swag init必须在包含main.go的项目根目录执行；如果main.go在cmd/server/main.go，就得先进入该目录再运行 - 默认只扫描当前目录及子目录，不递归扫描同级其他模块；若 handler 分散在
internal/handler和api/user.go，需加--dir ./...或明确指定多个路径（Swag 不支持 glob，只能用--dir多次） -
@title、@version等全局注释必须写在main.go（或通过-g指定的文件）里，且不能被注释符号（//）以外的字符隔开 —— 比如空行、/* */块注释、import 后的 blank line 都会导致解析失败
gin-swagger 页面打开空白或报 404？路由注册顺序错了
ginSwagger.WrapHandler(swaggerFiles.Handler) 必须在所有业务路由注册之后、r.Run() 之前挂载，否则中间件匹配不到 /swagger/*any 路径：
- 错误写法：
r := gin.New()后立刻注册 swagger 路由，再加载其他 group —— 此时gin.Default()的 logger/recovery 中间件还没生效，可能导致 panic 不被捕获，swagger 路由也失效 - 正确顺序：先
r := gin.Default()，再r.Group(...)加业务路由，最后r.GET("/swagger/*any", ...) - 注意
/*any是 Gin 的通配符语法，不能写成/*或/swagger/—— 否则子路径如/swagger/index.html无法命中
结构体字段没出现在请求/响应示例中？字段导出与 tag 冲突
Swag 只识别首字母大写的导出字段（即 Go 的 public 字段），且会优先读取 json tag，而非 struct 字段名：
立即学习“go语言免费学习笔记（深入）”；
- 字段
ID int `json:"id"`→ 文档中显示为id: integer；但若写成ID int `json:"-"`，该字段就完全不会出现在文档里 - 嵌套结构体必须也是导出类型，且不能是
map[string]interface{}或interface{}—— Swag 无法反射解析，会显示为object无具体内容 - 数组字段如
Users []User，需在@Success或@Param中显式写{array}User，不能只写User
文档更新了但 Swagger UI 没变？缓存和导入没刷新
Swagger UI 页面本身有强缓存，且 Go 运行时只加载一次 docs/docs.go：
- 每次改完注释，必须重新运行
swag init，否则docs/swagger.json不更新 -
_ "your_project/docs"导入语句中的包路径必须和实际生成的docs目录位置一致 —— 比如swag init -o internal/docs后，导入就得写_ "your_project/internal/docs" - 浏览器访问
/swagger/index.html时按Ctrl+Shift+R硬刷新，或禁用缓存调试（DevTools → Network → Disable cache）
Swag 不是“装完就能用”的黑盒，它依赖注释的机械解析和 Go 包导入机制的精确配合。最容易忽略的是：注释必须紧贴函数声明、docs 包必须被 import（哪怕用 _）、swag init 的工作目录必须覆盖全部源码 —— 少一个，文档就断在某处，而错误提示几乎为零。
