swag 生成 API 文档时接口未显示，主因是扫描路径未覆盖 handler 文件或 package 不合法；@Param 报错因 type 只支持基础类型或 @Model 定义的 struct；中文乱码源于 swagger.json 编码异常或注释含非法字符。
用 swag 生成 Go API 文档，但接口没出现在 HTML 里？
常见现象是跑完 swag init，docs/docs.go 生成了，也能启动服务，但浏览器打开后只有空页面或只显示首页，所有 @Summary 标记的接口全丢了。
根本原因不是注释写得不对，而是 swag 默认只扫描当前目录及其子目录下带 .go 后缀的文件，且要求这些文件属于同一个 Go module（即有 go.mod）。如果 handler 分散在 internal/ 或 pkg/ 下，又没显式指定路径，就会漏扫。
- 执行时加
-g参数指向主入口文件，比如swag init -g cmd/myapp/main.go - 用
-d显式声明要扫描的目录，多个目录用空格分隔：swag init -d internal/handler -d pkg/api - 确保所有被扫描的
.go文件里都有有效的package声明，且不能是package main（除非它真包含路由注册逻辑） - 别把
@Success写在函数体里——必须紧贴在 HTTP handler 函数声明上方，且中间不能有空行
swag 注释里怎么写 @Param 才不报错？
最常卡在 swag init 报 ParseComment error，提示类似 unknown type "string" for param 或 cannot find type definition。这不是类型名写错了，而是 swag 对参数类型的解析规则和 Go 实际类型系统不一致。
它不认别名、不认结构体字段嵌套、也不自动展开 map[string]interface{}。所有 @Param 的 type 字段只能填基础类型名或已通过 @Model 显式定义过的 struct 名。
立即学习“go语言免费学习笔记（深入）”；
- 路径参数、查询参数、请求头统一用
string、int、bool等原始类型，别写int64或uuid.UUID - 请求体（
in: body）必须对应一个已定义的 struct，并在该 struct 上方加@Model注释 - 数组参数写成
type: array+items.type: string，不能简写为type: []string - 如果用了 Gin 的
c.Param("id")，注释里@Param的name必须和路由里写的完全一致，包括大小写
生成的文档里中文乱码或样式错位？
不是字体问题，是 swag 生成的 docs/swagger.json 编码或字段值本身含非法字符。典型表现：中文 @Description 显示成 \u4f60\u597d，或者 Swagger UI 加载失败报 Unexpected token 。
根本原因是 Go 源文件保存编码不是 UTF-8（比如 GBK），或者注释里混入了不可见控制字符（比如从 Word 或微信复制过来的引号、换行符）。
- 用
file -i your_handler.go检查文件编码，非utf-8就重存为 UTF-8（VS Code 右下角可切换） - 删掉所有注释里的全角标点、智能引号、零宽空格（可用 VS Code 的“显示不可见字符”功能）
- 避免在
@Description里直接写多行文本，改用@Description("第一行。\n第二行。")，注意双引号内换行要用\n - 如果用了
swag的--parseVendor，确认 vendor 目录下没有损坏的第三方包注释
Gin 路由注册后文档里路径还是 /api/v1/users/{id} 而不是实际前缀？
这是因为 swag 不读取运行时的路由树，只静态分析源码。它看到的是你写的 router.GET("/users/{id}", ...)，并不知道这个 handler 是挂在 router.Group("/api/v1") 下面的。
结果就是生成的 swagger.json 里 paths 键值是 "/users/{id}"，而不是预期的 "/api/v1/users/{id}"。Swagger UI 请求时会 404。
- 手动在
@Title或@Host注释下方加@BasePath /api/v1（注意没有斜杠结尾） - 如果用了多个 Group 前缀（比如 admin 和 user 分开），
swag不支持自动合并，得选一个主前缀，其余靠前端代理或后端路由层处理 - 别依赖
swag自动推导 prefix——它不会看router.Group()调用链，只认字面量字符串
文档能跑起来只是开始，真正难的是让每条注释都对得上运行时行为。尤其是当 handler 拆得细、group 嵌得深、参数类型自定义得多的时候，swag 的静态分析就很容易漏掉上下文。这时候与其反复调参数，不如先确认注释位置、文件编码、路径字面量这三件事有没有出岔子。
