swag init 生成 docs 失败主因是注释不规范或路径配置错误：@title/@version 必须在 main.go 顶部，handler 注释需紧贴函数且含完整 @summary/@router，结构体字段须导出并带有效 json tag。
用 swag init 生成 docs 目录失败，提示找不到 @title 或解析错误
Go 里没有内置 Swagger 支持，得靠 swag 工具把注释转成 OpenAPI JSON。它不读代码逻辑，只扫描特定格式的注释块（叫 “swag comments”），所以第一关是注释写法必须严格。
常见翻车点：注释没紧贴函数声明、用了中文冒号、漏了必填字段、或在非 HTTP handler 函数上乱加。比如：
// @Summary 获取用户信息
// @Description 根据 ID 返回用户详情
// @Tags users
// @Accept json
// @Produce json
// @Param id path int true "用户ID"
// @Success 200 {object} model.User
// @Router /users/{id} [get]
func GetUser(w http.ResponseWriter, r *http.Request) { ... }
-
@title和@version必须写在 main 包的某个 Go 文件顶部（通常是main.go），不能放在 handler 文件里 -
@Param的第三个字段是数据类型，int、string、boolean是合法值，int64或*int会报错 - 如果 handler 返回指针类型（如
*User），@Success得写成{object} model.User，不是{object} *model.User
struct 字段没出现在 Swagger 的 response schema 里
Swagger 生成的 schema 来自 Go struct 的导出字段（首字母大写）+ JSON tag。如果字段没出现在文档里，大概率是它没被序列化——要么没导出，要么 JSON tag 设成了 - 或空字符串。
比如这个结构体：
type User struct {
ID uint `json:"id"`
Name string `json:"name"`
pwd string `json:"-"` // 小写开头 + json:"-" → 不导出也不显示
}
- 确保字段名首字母大写（
Pwd而不是pwd） - 检查
json:tag：设为"-"会跳过序列化，Swagger 就看不到；设为"omitempty"没影响，仍会出现在 schema 中 - 嵌套 struct 要同样满足导出 + 有效 tag，否则整个字段在 schema 里显示为
object而无具体属性
启动服务后访问 /swagger/index.html 显示 404
生成的 docs 目录只是静态资源，Go HTTP 服务默认不自动提供它。你得手动注册路由并挂载文件服务器。
别直接用 http.FileServer，要配合 http.StripPrefix 去掉路径前缀，否则页面里的 JS/CSS 请求会 404：
import "github.com/swaggo/http-swagger"
// 在你的 router 里加这一行（比如用 net/http）
http.Handle("/swagger/", http.StripPrefix("/swagger/", http.FileServer(http.Dir("./docs/"))))
// 或者更省事：用官方封装好的 handler
http.Handle("/swagger/", http-swagger.WrapHandler)
-
./docs/路径必须和swag init输出的目录一致；如果用了-o指定输出位置，这里要同步改 - 用
http-swagger.WrapHandler时，它默认监听/swagger/，但内部重定向逻辑依赖这个路径，别改成/api/swagger之类 - 某些框架（如 Gin）有专用中间件，不要混用标准库的
FileServer和框架路由，容易冲突
POST 接口的 request body 总是显示为 empty object
Swagger 默认只从 @Param 注释推断 path/query/header 参数，body 需显式用 @Param + body 类型声明，并指向一个已定义的 struct。
错误写法：// @Param user body models.User true "用户数据" —— 这样只会生成空 schema，因为没告诉 swag 这个 struct 长什么样。
- 确保
models.User是一个真实存在的、可导出的 struct，且所在包已被swag init扫描到（通过-g指定入口文件） - 如果 struct 在独立的
models包里，运行swag init时要加-g ./main.go（指向 main 包），否则不会递归分析依赖包 - 避免用匿名 struct 或 map[string]interface{} 做 body，swag 解析不了它们的字段
真正起作用的是 struct 定义本身，而不是注释里写的类型名——注释只是提示，底层还是靠反射读取 struct tag。
