swag init 找不到 handler 文件是因为未正确指定扫描路径和入口文件，需用 -d 指定多目录、-g 指定 main 入口，且 handler 文件须非 package main、有合法包声明和无语法错误。
swag init 找不到 handler 文件？检查扫描路径和入口文件
swag init 后 docs/swagger.json 里 paths 为空，或者 UI 显示首页但没接口列表，90% 是因为根本没扫到你的 handler 函数。
- 默认只扫描当前目录及子目录下属于同一 Go 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 类型系统
报错类似 cannot find type definition for "uuid.UUID" 或 unknown type "int64"，不是你代码有问题，而是 swag 的类型解析器只认基础类型名和已用 // @Model 显式声明过的 struct。
-
@Param id path string true "用户ID"✅ —— 路径/查询/请求头参数只能用string、int、bool、float64，别写int64或uuid.UUID -
@Param user body model.User true "用户信息"✅ —— 请求体（in: body）必须指向一个已定义的 struct，且该 struct 上方需有// @Model注释 -
@Success 200 {object} model.UserResponse✅ —— 结构体必须导出（首字母大写），字段必须带json:"xxx"tag，否则字段不会出现在 schema 中 - 数组参数不能简写为
type: []string，而应写为：@Param ids query array true "ID列表" collectionFormat:multi items.type:string
Swagger UI 页面空白或加载失败？查路径映射和 docs.go import
打开 /swagger/index.html 页面空白，控制台报 Failed to load spec，说明前端请求 /swagger/swagger.json 返回了 404 或 HTML，根源在静态文件托管配置。
- Gin 用户：导入
github.com/swaggo/gin-swagger和github.com/swaggo/files，加一行：r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler)) - net/http 用户：用
http.FileServer挂载，注意路径映射：http.Handle("/swagger/", http.StripPrefix("/swagger/", http.FileServer(http.Dir("./docs"))))，确保GET /swagger/swagger.json可直接访问 - 必须确认生成的
docs/docs.go被项目 import（哪怕只是 blank import：_ "your-module-path/docs"），否则swaggerFiles.Handler读不到内嵌数据
中文乱码、响应体显示 “object”、字段全空？检查三个硬性条件
文档加载后中文变 \u4f60\u597d，或点开响应 schema 全是空对象，大概率不是配置问题，而是代码层面没满足 swag 的硬性要求。
立即学习“go语言免费学习笔记（深入）”；
- 所有注释必须 UTF-8 编码，保存时禁用 BOM
-
@Model注释必须紧贴 struct 定义上方，中间不能有空行；struct 必须在被扫描的 package 内，且该 package 已被 import - struct 字段未导出（小写开头）+ 缺少
json:tag → 字段直接消失；字段有json:"-"→ 字段被忽略；字段类型是map[string]interface{}或匿名 struct → swag 解析不了，显示为空 object
