swag是Go生态中唯一稳定落地的API文档自动生成方案，需正确指定扫描路径、入口文件及package声明，严格遵循@Param/@Success类型规则、UTF-8编码、导出字段与json tag、@Model注释位置，并通过自动化测试校验文档与接口一致性。
swag 是当前 Go 生态中唯一能稳定落地的 API 文档自动生成方案，GoFrame 的 net/goai 模块虽已支持 OpenAPI 3.0，但生产环境仍建议优先使用 swag —— 它成熟、可控、错误反馈明确，且与 CI/CD 流程天然契合。
swag init 扫不到接口？确认扫描路径和 package 声明
执行 swag init 后 docs/swagger.json 中 "paths":{}，或 Swagger UI 空白，本质是 swag 根本没加载到 handler 文件。
- 默认只扫描当前目录及子目录下属于同一 Go module 的
.go文件；若路由分散在internal/handler、pkg/api，必须显式指定：swag init -d internal/handler -d pkg/api - 入口文件（如
cmd/app/main.go）需用-g指定：swag init -g cmd/app/main.go，否则可能漏掉跨包注册的r.POST()调用 - 被扫描的 handler 文件不能是
package main（除非它直接含路由注册逻辑），推荐统一用package handler或package api - 所有文件必须有合法
package xxx声明，且无语法错误——任一文件报错，整个包都会被跳过
@Param 和 @Success 类型写错？swag 不认 Go 类型系统
swag 的类型解析器和 Go 编译器不一致：它只识别基础类型名（string、int、bool、float64）和已用 // @Model 显式声明的 struct。
-
@Param id path string true "用户ID"✅ —— 路径/查询/请求头参数只能写string，别写int64或uuid.UUID -
@Param user body model.User true "用户信息"✅ —— 请求体必须指向一个已定义 struct，且该 struct 上方需有// @Model注释 -
@Success 200 {object} model.UserResponse✅ —— 结构体必须导出（首字母大写），字段必须带json:tag，否则字段不会出现在 schema 中 - 数组参数要写全：
@Param ids query array true "ID列表" collectionFormat:multi items.type:string，不能简写为type: []string
中文乱码、响应体显示 “object”、字段全空？检查三个硬性条件
文档加载后中文变 \u4f60\u597d，或点开响应 schema 全是空对象，不是配置问题，而是代码层面没满足 swag 的硬性要求：
- 所有注释必须用 UTF-8 编码保存，编辑器不能存成 GBK 或其它编码
- 结构体字段必须导出（首字母大写），且每个字段必须有
json:tag，例如Name string `json:"name"`；没有 tag 的字段会被忽略 -
@Model必须放在 struct 定义正上方，且中间不能有空行；多个@Model注释只认第一个
自动化测试如何验证生成的文档是否与接口一致？
不能只靠人工点开 Swagger UI 看——要让测试脚本自动校验关键字段是否存在、参数是否必填、状态码是否覆盖。
立即学习“go语言免费学习笔记（深入）”；
- 用
go test启动一个临时 server（如httptest.NewServer），访问/swagger.json获取原始 spec - 解析 JSON，断言
paths["/login"]["post"]["parameters"]长度 ≥ 2，且其中一项name == "username"且required == true - 检查
paths["/user/{id}"]["get"]["parameters"]中in == "path"且name == "id" - 集成进 CI：每次
swag init后立即跑这个校验测试，失败即阻断发布
json: tag、调整了路由路径，就必须重新 swag init 并触发文档一致性校验——否则测试通过，文档却已失效。 
