注释必须写在http handler函数正上方且紧邻，中间不能有空行或其它语句；函数须被路由注册，swag init需在模块根目录运行并正确指定扫描路径。
Swagger 注解写在哪儿才生效
Go 服务里加了 @swagger:route 或 // @Summary 注释，但生成的文档里没内容？大概率是注解位置错了。Swagger 工具（比如 swag）只扫描 func 声明上方紧邻的注释块，且该函数必须被 http.HandleFunc 或 Gin/Echo 的路由注册调用到。
常见错误：
- 把注释写在 handler 内部逻辑里（比如
if分支中），不会被识别 - 注释和函数之间夹了空行或其它语句，
swag就认为“断开”了 - 用了第三方中间件封装 handler（如 auth wrapper），但注释写在 wrapper 函数上，而非最终业务 handler
正确写法示例：
// @Summary 获取用户详情
// @ID getUser
// @Accept json
// @Produce json
// @Param id path int true "用户ID"
// @Success 200 {object} UserResponse
func GetUserHandler(c *gin.Context) {
// ...
}
swag init 为什么总报错找不到 docs
执行 swag init 后提示 failed to find docs 或 no swagger comments found，不是代码问题，而是工作目录或扫描路径不对。
关键点：
-
swag init必须在 Go 模块根目录运行（即含go.mod的目录），否则无法解析 import 路径 - 默认只扫描当前目录及子目录下的
*.go文件；如果 handler 分散在internal/handler和api/v1等多目录，得显式指定：swag init -g cmd/main.go -d internal/handler,api/v1 - 若用了 Go 1.21+ 的 workspace 模式，
swag不识别 workspace 配置，必须切到具体 module 目录下运行
Gin handler 参数绑定和 Swagger 类型不一致
Gin 用 c.ShouldBindQuery 或 c.ShouldBindJSON 解析参数，但 Swagger 文档里显示的类型和实际结构对不上——比如 query 参数标成了 string，但后端接收的是 int64。
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
这是因为 swag 不会自动推导绑定逻辑，所有参数类型、是否必填、默认值都得手动声明：
- query/path/header 参数用
@Param显式定义，type必须和 Go 类型一致（integer对应int/int64，string对应string） - body 参数用
@Param+{object}引用结构体，且该结构体必须有可导出字段 + JSON tag（如json:"name"），否则字段不出现 - 别依赖
swag fmt自动补全，它只格式化注释，不修正语义
示例（避免整型被当成字符串）：
// @Param page query int false "页码" default(1) // @Param limit query int false "每页数量" default(20)
微服务间接口引用导致文档混乱
多个微服务共用一套 model 包（如 github.com/org/common/model），但 swag init 生成时把所有 struct 全扫进去了，文档里堆满无关模型，甚至出现重复定义。
根本原因是 swag 默认递归解析所有 import 的包。解决方式只有两个：
- 用
-exclude排除外部模块：swag init -exclude "github.com/org/common/.*" - 把对外暴露的 DTO 单独抽到
api/dto目录，并只扫描该目录：swag init -d api/dto
注意：不要试图用 // @name 重命名 struct 来“覆盖”，Swagger UI 不认这个，只会让 spec 校验失败。
最麻烦的其实是跨服务调用链路的文档联动——Swagger 本身不支持服务间引用，得靠 OpenAPI 的 $ref 手动维护，或者换用专门的 API 网关层统一聚合文档。这点容易一开始忽略，等服务多了才踩坑。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
