swag init扫不到接口是因为默认只扫描当前目录同module的.go文件，需用-d指定多目录、-g指定入口文件，且handler文件不能是package main、须有合法声明和正确注释。
swag init 扫不到接口？先确认 package 和扫描路径
swag 不会跨 module 自动发现 handler，它只认当前 swag init 所在目录下、且 package 声明合法的 .go 文件。常见现象是生成的 docs/swagger.json 里 "paths":{} —— 根本没接口。
- 必须用
-d显式指定所有含 handler 的目录，比如swag init -d ./api -d ./internal/handler；swag 不支持 glob 或通配符 - 被扫描的文件不能是
package main（除非它真注册了路由），否则会被跳过；推荐把路由逻辑放在package router或package api -
-g参数必须指向含main()的入口文件，例如swag init -g cmd/myapp/main.go，否则跨包调用的路由注册可能漏掉 - 任何被扫描的
.go文件若有语法错误（比如少个括号、import 错误），整个文件会被静默忽略
@Param 和 @Success 写错类型？swag 不认 Go 类型系统
报错 cannot find type definition for "uuid.UUID" 或文档里字段全空，不是代码写错了，而是 swag 的类型解析器和编译器不一致：它只认基础类型名 + 已声明的 struct。
- 路径/查询/请求头参数只能用
string、int、bool、float64；别写int64或uuid.UUID - 请求体（
in: body）必须指向一个已定义的 struct，且该 struct 上方需有// @Model注释 -
@Success 200 {object} model.UserResponse中的model.UserResponse必须导出（首字母大写），字段必须带json:tag；没 tag 的字段不会出现在 schema 里 - 数组参数不能简写为
type: []string，得写成@Param ids query array true "ID列表" collectionFormat:multi items.type:string
中文乱码、响应显示 “object”、字段为空？三个硬性条件缺一不可
文档加载后中文变 \u4f60\u597d，或点开 response schema 全是空对象，大概率是代码层面没满足 swag 的硬性要求，不是配置问题。
- 结构体字段必须导出（首字母大写）且带
json:tag；哪怕字段名是UserName，没写json:"user_name"就不会出现 - 嵌套 struct 必须逐层导出 + 逐层加 tag；
map[string]interface{}或interface{}无法解析，会显示为object无内容 -
time.Time字段建议显式写json:"created_at" time_format:"2006-01-02T15:04:05Z"，否则可能输出为 float64 时间戳 - 忽略字段用
json:"-"，swag 会跳过该字段；但别滥用，否则文档缺失关键字段
gin-swagger 页面空白或 404？路由注册顺序和通配符写法必须精确
页面打开后空白，或访问 /swagger/index.html 返回 404，基本是路由挂载位置或路径匹配规则不对。
-
ginSwagger.WrapHandler(swaggerFiles.Handler)必须在所有业务路由注册之后、r.Run()之前挂载 - 必须用
/swagger/*any，不能写成/swagger/或/swagger/*；Gin 的*any是通配符语法，缺一不可 - 如果用了
gin.Default()，确保 swagger 路由注册在 logger/recovery 中间件生效之后，否则 panic 可能导致路由失效 - Docker 构建时必须显式
COPY docs/ docs/，IDE 或 CI 流程常忽略该目录
swag init，且要验证生成的 docs/swagger.json 是否真正包含预期字段——别只看 UI 是否能打开。大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
