swag是Go生态中唯一稳定落地的API文档自动生成方案，但需确保文档与接口行为一致；须正确配置扫描路径、入口文件、package声明及注释规范，并通过go test自动化校验请求响应一致性。
swag 是当前 Go 生态中唯一能稳定落地的 API 文档自动生成方案，但仅生成文档远远不够——文档必须和接口行为一致，否则就是误导。自动化验证的核心不是“有没有文档”，而是“文档描述的请求/响应是否真能跑通”。
swag init 扫不到接口？路径、入口、package 三者缺一不可
swag init 后 docs/swagger.json 中 "paths":{}，或 Swagger UI 空白，根本原因是它压根没加载到 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 的硬性要求：
- 所有注释（
@Param、@Success、// @Model）必须是 UTF-8 编码，保存时禁用 BOM -
@Success引用的 struct 必须导出（首字母大写），且每个字段都带json:tag，例如Name string <code>json:"name"；漏掉任意一个 tag，字段就消失 -
// @Model注释必须紧贴 struct 定义上方，中间不能有空行或其它语句，且 struct 名必须和@Success中写的完全一致（大小写敏感）
如何自动化校验文档与接口一致性？用 go test 驱动真实 HTTP 调用
生成文档只是第一步，真正关键的是用测试代码把swagger.json 里的每个 path 和 method 跑一遍，检查状态码、响应结构、字段类型是否匹配。
- 在
api_test.go中启动一个测试用的 HTTP server：httptest.NewServer，确保它加载全部 handler - 解析
docs/swagger.json，提取所有paths和parameters，构造真实请求（注意query参数要 URL encode，body要 JSON marshal） - 对每个 endpoint，断言：
- 返回状态码符合
@Success/@Failure声明 - 响应 body 能成功 JSON unmarshal 到对应 struct（用
json.Unmarshal+ 类型断言） - 字段值符合预期（例如
Code== 0，Data不为 nil）
- 返回状态码符合
- 把这个测试加进 CI 流程：
go test -run=TestSwaggerConsistency，文档一改错，CI 直接红
真正容易被忽略的点是：文档验证测试本身依赖于运行时服务状态，所以必须确保测试 server 和实际 handler 完全对齐——比如中间件顺序、JWT 校验开关、mock 数据初始化时机，稍有偏差，验证就失去意义。
