swag init 生成的 docs 没有接口，最常见原因是 handler 函数上方未添加 // @Router 和 // @Success 等注释，且注释必须紧贴函数声明、无空行；同时需用 -d 参数指定多目录路径，如 ./handlers,./api。
为什么 swag init 生成的 docs 没有接口？
最常见原因是没在 handler 函数上方加 // @Router 和 // @Success 等注释。Swag 不解析函数体，只扫描注释块，且要求注释紧贴函数声明（中间不能有空行）。
另外，swag init 默认只扫描当前目录及子目录下的 .go 文件，如果路由注册和 handler 分散在不同包（比如 handlers/ 和 api/），需显式指定路径：
swag init -g main.go -d ./handlers,./api不加
-d 参数时，它根本不会看其他目录。
如何让 @Param 正确识别 query/path/header 参数？
参数类型必须与实际接收方式严格匹配，否则 Swagger UI 不会渲染输入框或下拉项。
常见写法：
-
// @Param id path string true "用户ID"→ 对应/:id路由段 -
// @Param page query int false "页码" default(1)→ 解析 URL 查询参数?page=2 -
// @Param X-Auth-Token header string true "认证Token"→ 提取请求头
注意：default、enum、minimum 等修饰符必须写在引号外，且中间无空格；string 和 int 是 Swagger 支持的基础类型，不要写 uint64 或自定义 struct 名。
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
如何避免 swag init 报错 “undefined type”？
Swag 在解析注释时会尝试校验结构体是否可导出、字段是否可序列化。报这个错通常是因为：
• 注释里写了 // @Success 200 {object} models.User，但 models.User 所在包没被当前扫描文件 import；
• User 字段未导出（小写开头），或嵌套了不可序列化的类型（如 func()、map[interface{}]string）；
• 使用了别名类型（如 type UserID int64），但没加 // @Model 注释说明。
立即学习“go语言免费学习笔记（深入）”；
解决方法：
• 确保所有被引用的结构体都出现在扫描路径中，且被至少一个 .go 文件 import；
• 用 // @Model 显式声明别名或嵌套结构：
// @Model User
// @Description 用户基本信息
type User struct {
ID int64 `json:"id"`
Name string `json:"name"`
}
如何把 Swagger UI 集成进 Gin/Echo 路由？
Swag 生成的是静态资源（docs/docs.go），不是 HTTP 服务。集成关键在于注册路由时指向正确的 handler：
• Gin：
import _ "your-project/docs"
r := gin.New()
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))• Echo：
e := echo.New()
e.GET("/swagger/*", echoSwagger.WrapHandler(swaggerFiles.Handler))注意：
/swagger/*any 中的 *any 是 Gin 的通配符写法，Echo 用 *；路径末尾斜杠、大小写必须和生成的 docs/swagger.json 实际路径一致（默认是根路径下）；如果改过 swag init -o 输出目录，要同步更新 swaggerFiles.Handler 的资源加载逻辑。
最容易被忽略的是：每次修改接口注释后，必须重新运行 swag init，否则浏览器访问看到的仍是旧文档——它不热重载，也不监听文件变化。
