swag init 依赖导出函数前的正确 Swagger 注释，注释缺失或格式错误会导致静默跳过或报错；生成的 docs 需手动挂载路由，且路径、模型定义、目录扫描等均需严格匹配规范。
Go 项目里不写 Swagger 注释，swag init 就跑不起来
Go 没有运行时反射导出接口信息的能力，swag 这类工具完全依赖源码里的特殊注释（比如 // @Summary）来生成文档。没加注释，或注释格式错一个字符，swag init 就会静默跳过这个 handler，或者报 ParseComment error。
- 必须在 HTTP handler 函数上方写注释，且函数需导出（首字母大写）
-
// @Router路径要和实际路由注册一致，包括参数占位符写法：/users/{id}≠/users/:id - 结构体字段若要出现在请求/响应示例中，得加
json:tag，且字段必须导出（UserName string `json:"user_name"`） - 别把注释写在函数内部——
swag只扫描函数声明前的紧邻注释块
用 swag init 生成 docs，但访问 /swagger/index.html 显示 404
生成的 docs 目录只是静态文件，不会自动挂载到 HTTP 路由。你得手动用 http.FileServer 或框架中间件暴露它。
- 标准库用法：
http.Handle("/swagger/", http.StripPrefix("/swagger/", http.FileServer(http.Dir("./docs")))) - gin 框架需额外引入
github.com/swaggo/files和github.com/swaggo/gin-swagger，然后调用ginSwagger.WrapHandler(swaggerFiles.Handler) - 路径前缀必须和
swag init -u指定的 URL 前缀一致，否则 JS 加载swagger.json会 404 - 生成后检查
docs/swagger.json是否真实存在、内容是否为空——空文件多半是注释漏了@Success或@Failure
struct 字段没出现在 Swagger UI 的 Model 里
Swagger UI 的 Model 展示只来自你显式标注的结构体（如 // @Param req body models.UserCreate true "user" 中的 models.UserCreate），且仅包含导出字段 + 有效 json tag。
- 未导出字段（小写开头）直接被忽略，哪怕写了
json:tag -
json:"-"或json:""会让字段不出现在 JSON 中，Swagger 也不会显示 - 嵌套结构体必须也定义在
models包下（或用// @model显式标记），否则生成器不认识类型 - 切片、指针、map 等复合类型需明确写成
[]models.Item、*models.Item，不能只写[]string—— 后者虽能生成，但 Model 树里看不到结构细节
开发时改了注释但 swag init 不更新 docs/swagger.json
swag 默认只扫描 ./... 下的 Go 文件，如果 handler 分散在多个子模块（比如 api/v1/、handlers/），不指定路径就会漏掉。
- 运行命令时加
-d参数明确目录：swag init -d ./api -d ./handlers - 确保没被
.swaggo或docs/自身目录干扰——swag会跳过含docs/的路径 - 修改注释后记得删掉旧的
docs/目录再重新生成，避免缓存残留 - CI 流水线里建议加校验：
swag init && git diff --quiet docs/swagger.json || (echo "swagger.json out of date"; exit 1)
最常被忽略的是注释和路由注册的耦合关系：写对了 @Router，但实际用 router.POST("/v1/users", ...) 注册，而注释里写的是 @Router /users [post]——这种不一致不会报错，但文档里就少了版本前缀，前端联调时容易懵。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
