swag init 生成的 docs 文件里没有接口，根本原因是 handler 函数缺少正确格式的 Swagger 注释或函数未导出；Gin 路由参数需手动用 @Param 声明；Swagger UI 需通过 gin-swagger 包注册路由；struct 字段必须导出并正确打 tag 才能显示在响应模型中。
为什么 swag init 生成的 docs 文件里没有接口？
根本原因通常是没在 handler 函数上加正确的 Swagger 注释，或者注释格式被 Go 解析器跳过了。Gin 的路由注册方式（比如用 router.GET("/user", handler)）本身不携带任何文档元信息，swag 完全依赖源码里的注释块来生成 JSON Schema。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 每个 handler 函数上方必须紧贴着写
// @Summary、// @Tags、// @Param等注释，不能隔空行 - 确保 handler 是导出函数（首字母大写），否则
swag扫描不到 - 如果 handler 是闭包或匿名函数，
swag无法识别——得拆成独立函数再绑定路由 - 运行
swag init -g main.go时，-g指定的入口文件必须能 import 到所有 handler 所在包
Gin 路由参数怎么写进 Swagger 文档？
Gin 的 :id 和 *filepath 这类路径参数，不会自动变成 Swagger 的 path 参数，必须手动声明。否则文档里就只显示 URL 模板，不带参数定义，前端或测试工具无法自动生成请求。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 对
/users/:id，要加// @Param id path int true "用户ID" - 对
/files/*filepath，用// @Param filepath path string true "文件路径" -
@Param的第二个字段必须是path、query、body或header，写错（比如写成url）会导致该参数消失 - 如果用了
c.Param("id")但没写@Param注释，Swagger 就当这个参数不存在
如何让 Swagger UI 在 Gin 服务里跑起来？
不是把 docs 目录扔进静态文件服务就行。Gin 默认不支持直接 serve Swagger 的 index.html + swagger.json 组合，缺了 JS 初始化逻辑会白屏或报 404。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 用官方推荐的
github.com/swaggo/gin-swagger+github.com/swaggo/files - 注册路由时写
router.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))，注意/swagger/*any的通配写法不能省 -
swaggerFiles.Handler是预编译的嵌入式 FS，别试图用gin.StaticFS加载本地docs目录——跨平台路径和 MIME 类型容易出错 - 启动后访问
/swagger/index.html，不是/swagger/（后者会重定向失败）
struct 字段不显示在 Swagger 的 Response Model 里？
Swagger 的 model 是从 struct 定义推导的，但 Go 的字段可见性、tag 写法、嵌套深度都会打断推导链。常见现象是 Response 显示 {} 或字段全空。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- struct 字段必须导出（首字母大写），否则
swag当它不存在 - 用
json:tag 控制字段名，同时加swaggertype:指定类型，比如CreatedAt time.Time `json:"created_at" swaggertype:"string"` - 嵌套 struct 要单独写
// @Success 200 {object} YourResponseStruct，不能写{object} pkg.YourResponseStruct（包名不识别） - 如果用了
map[string]interface{}或interface{}，Swagger 无法生成 schema，得换成具体 struct
最常被忽略的是注释位置和 struct 导出性：一个 handler 上方漏了 @Success，或者返回 struct 里有个小写字段，整块响应模型就塌了。
