swag init 生成的 docs 中无接口，根本原因是 handler 函数缺少紧贴声明前的 // @Summary 等规范注释，或注释位置错误、使用匿名函数、未正确指定扫描路径。
为什么 swag init 生成的 docs 文件里没有接口？
根本原因通常是没在 handler 函数上方加正确的 // @Summary 等注释，或者注释位置不对——Gin 路由注册和注释必须在同一个 .go 文件里，且注释得紧贴函数声明前（不能隔空行、不能在函数体内）。
-
swag init只扫描 Go 源码里的注释，不解析路由注册逻辑；它不知道r.GET("/user", handler)对应哪个函数，除非你手动给handler加文档注释 - 如果 handler 是闭包或匿名函数（比如
r.GET("/user", func(c *gin.Context) {...})），swag完全无法识别，必须拆成具名函数 - 确保
swag命令运行时工作目录包含所有要扫描的 Go 文件，且-g参数指向正确的 main 入口文件（如swag init -g cmd/main.go） - 常见错误现象：
docs/docs.go生成了但swagger.json里"paths":{}为空——基本就是注释没写对或没写
Gin handler 注释怎么写才被 Swagger 识别？
不是随便写几行 // 就行，必须用 @ 开头的特定字段，且顺序和大小写敏感。最简可用组合只有三个：
-
// @Summary 获取用户信息（必填，否则接口不显示） -
// @Tags user（推荐填，否则所有接口堆在 default 分组） -
// @Router /users/{id} [get]（必须和实际路由完全一致：路径带参数花括号、HTTP 方法大写）
示例：
// @Summary 获取单个用户
// @Tags user
// @Accept json
// @Produce json
// @Param id path int true "用户ID"
// @Success 200 {object} model.User
// @Router /users/{id} [get]
func GetUser(c *gin.Context) {
// ...
}
注意：@Param 的 path / query / body 类型必须和实际接收方式匹配；@Success 后面的结构体得是可导出的（首字母大写），且最好已用 swag 扫描过（即定义在某个 .go 文件里）
立即学习“go语言免费学习笔记（深入）”；
如何让 Swagger UI 在 Gin 中跑起来？
别直接用 github.com/swaggo/files —— 它是旧版，Gin v1.9+ 默认用 net/http 的 FS 接口，得配 http.StripPrefix 和 http.FileServer。
- 先确保已运行
swag init，生成了docs/目录 - 在 Gin 路由里加这三行（顺序不能错）：
import "github.com/swaggo/gin-swagger"
import "github.com/swaggo/files"
// ...
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
注意：gin-swagger 是适配层，files 是静态资源，两者缺一不可；路径必须是 /swagger/*any（带通配符），否则 UI 加载 JS/CSS 会 404
在 Go 中使用 google/wire 实现编译时依赖注入——wire.NewSet、wire.Build、wire.Bind（接口→实现）、wire.Struct、wire.Value、wire.Interface
如果访问 /swagger/index.html 显示白屏，大概率是 docs/swagger.json 路径不对或内容为空——检查 swag init 输出日志里的 create docs/swagger.json 是否成功
为什么模型字段没出现在 Swagger Schema 里？
Go 结构体字段默认不会导出到 JSON，Swagger 也就看不到。关键就两点：
- 字段名必须首字母大写（Go 导出规则）
- 得有
json:tag，且不能是json:"-"或空字符串
比如这个结构体：
type User struct {
ID uint `json:"id"` // ✅ 出现在 Schema
Name string `json:"name"` // ✅
age int `json:"age"` // ❌ 小写开头，忽略
Tags []Tag `json:"tags,omitempty"` // ✅ 只要 Tag 类型也被 <code>swag</code> 扫描过
}
如果 Tag 定义在另一个包里，得在 swag init 时加上 -d 参数指定该包路径，否则 tags 字段只显示 {}
另外，swag 不支持嵌套泛型、函数类型、未命名结构体——这些都会 fallback 成 object，看着像丢了字段
复杂嵌套或需要自定义描述时，别依赖自动扫描，直接用 // @Schema 注释块手写定义，不然改半天 tag 都不如一行注释来得稳
