swag 是 Go 生态中唯一能稳定落地的 API 文档自动生成方案，通过静态解析源码注释生成 swagger.json；需确保 handler 文件被正确扫描（用 -d 指定路径、-g 指定入口）、结构体字段带 json tag、手动注入 Swagger UI 路由，否则接口将无声消失。
swag 是 Go 生态中唯一能稳定落地的 API 文档自动生成方案，它不依赖运行时反射，也不靠 YAML 手写，而是通过静态解析源码注释生成 swagger.json。别指望 go doc 或 godoc 能输出 REST 接口文档——它们只管包和函数说明。
swag init 找不到接口？先确认扫描路径和入口文件
执行 swag init 后 docs/swagger.json 里 "paths":{}，或 Swagger UI 页面空荡荡，大概率不是注释写错了，而是根本没扫到 handler 文件。
- 默认只扫描当前目录及子目录下属于同一 module 的
.go文件；handler 若在internal/handler或pkg/api，必须显式指定：swag init -d internal/handler -d pkg/api - 入口文件（如
cmd/app/main.go）要用-g指定：swag init -g cmd/app/main.go，否则跨包调用的路由注册逻辑会被跳过 - 被扫描的文件不能是
package main（除非它真包含r.GET()），推荐把路由逻辑单独放在package router或package api - 所有 handler 文件必须有合法
package xxx声明，且不能含语法错误，否则整文件被忽略
@Param 和 @Success 写错类型？记住 swag 不认 Go 类型系统
swag init 报 cannot find type definition for "uuid.UUID" 或 unknown type "string"，本质是它的类型解析器和 Go 编译器不一致：它只认基础类型名和已用 @Model 显式声明过的 struct。
- 路径/查询/请求头参数只能用
string、int、bool、float64；别写int64或uuid.UUID - 请求体（
in: body）必须指向一个已定义的 struct，且该 struct 上方需有// @Model注释 -
@Success 200 {object} model.UserResponse中的model.UserResponse必须导出（首字母大写），字段必须带json:tag，否则字段不会出现在 schema 中 - 数组参数写法是
@Param ids query array true "ID列表" collectionFormat:multi items.type:string，不能简写为type: []string
中文乱码、响应体显示 “object”、字段全空？检查三个硬性条件
文档加载后中文变 \u4f60\u597d，或点开响应 schema 全是空对象，大概率不是配置问题，而是代码层面没满足 swag 的硬性要求：
- Go 源文件编码必须是 UTF-8（用
file -i your_handler.go检查，非 utf-8 就重存） - 注释里不能混入不可见控制字符（比如从微信或 Word 复制的引号、换行符）
- 结构体字段若要出现在请求/响应示例中，必须带
json:tag，例如Name string `json:"name"`；否则swag无法推导字段名和类型
启动服务后 /swagger/index.html 404？你漏了手动注入路由这步
swag init 只生成静态资源，不自动注册 HTTP 路由。访问 /swagger/index.html 404，是因为你没把 docs.SwaggerInfo 挂到服务上。
立即学习“go语言免费学习笔记（深入）”；
- 用 Gin 时，得手动加路由：
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler)) - 路径前缀（如
/swagger）必须和前端请求 URL 完全一致，大小写、斜杠都不能错 - 别用
http.ServeFile——它不支持/*any通配，会 404 - 如果项目用了 vendor，记得加
--parseVendor参数，否则swag看不到 vendor 里的结构体定义
swag 根本没看到你的 handler 文件，或者结构体字段缺了 json: tag —— 这两个点一旦漏掉，整个接口就悄无声息地消失了。 
