swag 是 go 生态中唯一稳定落地的静态 api 文档生成方案，通过解析源码注释生成 openapi 3.0 文档；需正确指定扫描路径（-d）、入口文件（-g），确保 handler 文件包名合法、结构体带 // @model 和 json: tag，且 docs 包被 import。
Swag 是当前 Go 生态中唯一能稳定落地的 API 文档自动生成方案，它不依赖运行时反射，而是静态解析源码注释生成 OpenAPI 3.0 文档——这意味着你改一行注释，swag init 之后文档就同步更新，没有延迟、不需重启服务。
swag init 扫不到接口？检查扫描路径和入口文件
执行 swag init 后 docs/swagger.json 中 paths 为空，或 Swagger UI 显示首页但无接口列表，问题几乎总出在“没扫到 handler 文件”。
-
swag init默认只扫描当前目录及子目录下属于同一 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 "string"，本质是 swag 的类型解析器与 Go 编译器不一致：它只识别基础类型名和已用 // @Model 显式声明过的 struct。
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
-
@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:tag，否则字段不会出现在 schema 中 - 数组参数写法：
@Param ids query array true "ID列表" collectionFormat:multi items.type:string，不能简写为type: []string
中文乱码、响应体显示 “object”、字段全空？检查三个硬性条件
文档加载后中文变 \u4f60\u597d，或点开响应 schema 全是空对象，大概率不是配置问题，而是代码层面没满足 swag 的硬性要求。
- 源文件编码必须是 UTF-8（不含 BOM）
- 结构体字段必须有
json:tag，哪怕只是json:"name"；没 tag 的字段会被忽略或显示为interface{} - 嵌套结构体（如
User.Profile *Profile）需要Profile类型也在同一包或已import，且自身也带// @Model和字段json:tag，否则只显示object而无字段细节 - 返回指针（
*User）或切片（[]User）时，注释里要对应写{object} User或{array} User，二者语义不同
启动 docs 路由后页面 404 或 CSS 加载失败
调用 httpSwagger.WrapHandler 注册路由后，访问 /swagger/index.html 返回 404，或者页面空白、控制台报 swagger-ui.css:1 Failed to load resource，本质是静态资源没正确挂载。
- 确保
swag init成功执行，生成了docs/目录（含docs.go、swagger.json等），这个目录必须和二进制在同一级，否则httpSwagger找不到文件 - 必须在 main 包中 import 自动生成的 docs 包：
_ "github.com/your_project_path/docs"，否则swaggerFiles.Handler没有数据源 - 不要手动改
docs/doc.go里的docs.SwaggerInfo路径字段，它只影响 JSON 内容，不影响文件服务 - CI/CD 中需显式指定
-g入口路径，否则构建机上可能因工作目录不同导致docs/生成失败
最常被忽略的一点是：swag 不做类型推导，也不跨 module 自动发现 struct。你写的每一个 @Success、@Param body、@Model，都必须对应一个真实存在、可导出、带完整 json: tag 的 struct 定义，并且该定义要在当前文件可见范围内（通过 import 或同包）。漏掉任一环，schema 就会坍缩成空 object。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
