swag init 生成的 docs 没有接口，常见原因是 handler 函数上方未添加或未正确书写 Swagger 注释（如 // @Summary），或注释与函数间存在空行；swag 仅扫描符合规范的 Go 注释，不解析函数体或路由逻辑。
为什么 swag init 生成的 docs 没有接口？
常见原因是没在 handler 函数上方加 // @Summary 这类注释，或者注释没写在函数声明正上方（中间不能空行）。Go 的 swag 工具只扫描符合 Swagger 注释规范的 Go 注释，不解析函数体或路由注册逻辑。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 确保每个 HTTP handler 函数前紧贴着写完整注释块，例如：
// @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、@Success等标注，swag不会自动推导 struct 字段是否可为空或是否必填 - 如果用了
gin的c.ShouldBindJSON(&v)，记得给v对应的 struct 字段加上json:tag，否则swag无法识别字段名和类型
如何让 swag init 扫描到嵌套的 handler 文件？
swag init 默认只扫描当前目录及子目录下的 .go 文件，但如果你把 handler 分散在 handlers/、api/v1/ 等多层目录，又没显式指定入口，它可能漏掉部分文件。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 运行时加
-g参数指定主入口文件（通常是main.go），例如：swag init -g cmd/myapp/main.go - 用
-d显式指定要扫描的目录，支持多个：swag init -d internal/handlers -d internal/api - 避免在非 handler 文件（如 config、model）里写 Swagger 注释，否则容易污染文档或引发解析错误
Swagger UI 页面报错 “Failed to fetch” 或空白？
多数情况是生成的 docs/docs.go 没被引入，或静态资源路径没配对。Gin 默认不自动提供 /swagger/*any 路由，需手动挂载。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 确认已执行
swag init且生成了docs/docs.go文件；该文件必须被go build编译进去，不能被//go:build ignore排除 - Gin 中挂载方式必须用
ginSwagger.WrapHandler(swaggerFiles.Handler)，不是直接router.Static—— 后者不会处理swagger.json的动态生成 - 检查浏览器控制台：若提示
swagger.json 404，说明docs/docs.go未生效；若提示 CORS 错误，说明后端没开跨域（但 Swagger UI 本地打开时通常不走跨域）
struct 字段不显示在 Model 或参数中？
Swagger 文档里的 Model 完全依赖 struct 的字段 tag 和注释。没有 json: tag 的字段会被忽略，私有字段（首字母小写）默认不导出，即使加了 tag 也无效。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 所有要出现在文档中的字段必须是导出字段（大写开头），并带
json:tag，例如：Name string `json:"name"` - 用
// @description在 struct 上方补充说明，swag会将其作为 Model 描述：// @description 用户基本信息 type User struct { ID uint `json:"id"` Name string `json:"name"` } - 嵌套 struct 需要单独定义类型（不能用
map[string]interface{}或匿名 struct），否则swag无法解析其结构
