swag init 扫不到接口是因为默认只扫描当前 module 下的 .go 文件，需用 -d 指定 handler 目录、-g 指定入口文件，且 handler 不能是 package main；@Param/@Success 类型需为基础类型或已用 @Model 声明的 struct；中文乱码、字段为空因文件非 UTF-8、字段未导出或缺 json tag；Gin 集成需下划线导入 docs 包并正确注册路由。
swag init 生成的文档里没接口？不是注释写得不对，而是它根本没扫到你的 handler 文件。
swag init 扫不到接口，先看扫描路径和 package 声明
默认只扫描当前目录及子目录下属于同一 module 的 .go 文件。如果 handler 分散在 internal/handler、pkg/api 等路径，swag init 会直接跳过。
- 用
-d显式指定目录：swag init -d internal/handler -d pkg/api - 入口文件（如
cmd/app/main.go）要用-g指定：swag init -g cmd/app/main.go - 被扫描的文件不能是
package main（除非它真注册了路由），否则会被忽略；推荐把 handler 放在package handler或package api - 所有
.go文件必须有合法package xxx声明，且不能含语法错误，否则整文件被跳过
@Param 和 @Success 报 “unknown type”？swag 不认 Go 类型系统
swag 的类型解析器和编译器不一致：它只认基础类型名（string、int、bool、float64）或已用 // @Model 显式声明过的 struct。
- 路径/查询/请求头参数只能写
string、int，别写int64或uuid.UUID - 请求体（
in: body）必须指向一个已定义 struct，且该 struct 上方需有// @Model注释 -
@Success 200 {object} model.User中的model.User必须可导入（即import "your-module/model"），不能只写User - 数组参数写法是：
@Param ids query array true "ID列表" collectionFormat:multi items.type:string，不能简写为type: []string
中文乱码、响应体显示 “object”、字段全空？检查三个硬性条件
Swagger UI 加载后中文变 \u4f60\u597d，或点开 schema 全是空对象，大概率不是配置问题，而是代码层面没满足硬性要求：
立即学习“go语言免费学习笔记（深入）”；
-
.go文件保存编码必须是 UTF-8（用file -i your_handler.go检查，VS Code 右下角可切换） - 结构体字段必须导出（首字母大写）且带
json:tag，例如Name string `json:"name"`；否则字段不会出现在 schema 中 -
@Success或@Param body引用的 struct 必须有// @Model注释块，且紧贴 struct 定义上方，中间不能有空行
Gin 集成后访问 /swagger/index.html 404 或空白？漏了 docs 包导入
生成 docs/ 后，必须手动注入路由，且关键一步常被跳过：_ "your-module-name/docs" 这行下划线导入必须存在，否则 Swagger UI 加载不出内容。
- 确保
import列表中有这一行，且your-module-name和go.mod第一行完全一致（比如module github.com/you/project→ 导入_ "github.com/you/project/docs"） - Gin 用户加路由：
r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))，其中swaggerFiles是github.com/swaggo/files的 alias - 别把全局 API 注释（
@title、@version）写在函数里，必须放在main.go顶部（package main声明之后、任何函数之前）
最易被忽略的是：handler 函数注释必须紧贴函数声明上方，中间不能有任何空行；哪怕只多一个换行，swag 就认为注释不属于该函数，直接丢弃。
