swag init 扫不到接口是因为只识别带 @summary 和 @router 的可导出函数，且必须被入口文件 import 到、注释紧贴函数无空行、不在测试或忽略文件中，并需显式指定多路径扫描。
swag init 扫不到接口？不是路径写错了，是没满足静态解析的硬性前提——它只认带 @Summary 和 @Router 的可导出函数，且必须能被入口文件 import 到。
swag init 为什么找不到 handler 函数
swag 不扫描路由注册逻辑，也不分析 r.GET() 调用链，它只做一件事：在 Go 源码里找紧邻函数声明、格式合法的 Swagger 注释。
- 函数必须首字母大写（可导出），且定义在
swag init -g指定的入口文件能 import 到的包内 - 注释必须紧贴函数上方，中间不能有空行；至少含
// @Summary和// @Router - 别把 handler 写在
_test.go、mock_*.go或被//go:build ignore排除的文件里 - 如果 handler 分散在
internal/handler、pkg/api，必须显式指定扫描路径：swag init -d internal/handler -d pkg/api -g cmd/app/main.go
@Param 和 @Success 类型写错导致文档字段为空
报错 cannot find type definition for "uuid.UUID" 或响应体只显示 object，本质是 swag 的类型系统不等价于 Go 编译器——它只认基础类型名和已用 // @Model 显式声明的 struct。
Golang Spf13 Viper
下载
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 路径/查询/请求头参数只能写
string、int、bool、float64；别写int64或uuid.UUID - 请求体（
in: body）必须指向一个已定义的 struct，且该 struct 上方需有// @Model注释 - struct 字段要出现在 schema 中，必须同时满足：首字母大写（可导出）、带
json:tag、字段类型是基础类型或已声明的 struct - 数组参数不能简写为
type: []string，得写全：collectionFormat:multi items.type:string
Gin 中 c.Param() / c.Query() 怎么对应到 Swagger 注释
Swagger 注释不会自动推断 Gin 的参数提取方式，漏写就等于文档缺失——但接口照常运行，这是线上最隐蔽的“文档与实际不符”来源。
-
c.Param("id")→// @Param id path string true "用户ID" -
c.Query("page")→// @Param page query int false "页码" default(1) - body 参数必须用
// @Param request body YourStruct true "请求体"，且YourStruct是可导出、有json:tag 的 struct - 绝对不要用
map[string]interface{}或interface{}做请求体或响应字段，swag 解析不出结构，schema 里只剩空object
启动时 panic: failed to sync swagger.json: no such file or directory
这不是没跑 swag init，而是 Gin 加载 Swagger UI 时硬依赖 docs/swagger.json 存在且可读——哪怕你本地开发想跳过生成，也得先占个位。
- CI/CD 构建阶段必须执行
swag init -o docs/，不能只在本地跑 - 开发时可兜底：
mkdir -p docs && touch docs/swagger.json，但上线前务必替换为真实内容 - 检查
docs/是否被.gitignore误删——很多人提交时忘了加!docs/swagger.json - Gin 注册路由时路径别写成
/swagger/*any，正确是ginSwagger.WrapHandler(swaggerFiles.Handler)，否则静态资源 404
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
