Swag 仅将符合规范的 Go 注释和导出结构体转为 OpenAPI 文档，不构建标准化本身；需手动确保注释规范、字段导出、REST 路由设计，并显式指定扫描路径、正确挂载中间件、每次修改后重新执行 swag init。
Swag 不能“构建标准化 REST 文档”，它只负责把已有 Go 代码 + 注释转成 OpenAPI 2.0 格式文档；真正的标准化靠的是你写的注释是否符合规范、结构体是否导出、路由是否按 REST 风格设计——工具不替你做决策。
swag init 扫不到你的 handler 函数？路径和扫描范围没对
swag 默认只扫描当前目录（./）及其子目录，不会跨目录或同级模块自动查找。比如你的路由定义在 internal/handler/user.go，而 main.go 在项目根目录，swag init 就会静默跳过它。
- 必须用
--dir显式指定路径：swag init --dir ./internal/handler --dir ./api - 不能写
--dir ./internal/**—— Swag 不支持 glob，多个目录只能重复--dir - 确保
swag init在包含main.go的项目根目录运行，否则@title等全局注释无法被识别 - 如果 handler 分散在不同包，且用了
go mod子模块，需确认这些目录已通过go list可见，否则反射失败
GET /users 返回空对象？结构体字段没导出或 tag 写错了
Swag 依赖 Go 的反射机制读取结构体，只看首字母大写的导出字段（public field），且完全信任 json tag。字段名大小写、tag 值、嵌套类型都直接影响文档生成结果。
-
ID int `json:"id"`→ 文档中显示为id: integer；但ID int `json:"-"`→ 该字段彻底消失 -
CreatedAt time.Time `json:"created_at"`→ 正常显示；若漏了jsontag，Swag 会用字段名CreatedAt，不符合 REST 命名惯例 - 嵌套结构体如
User struct { Profile *Profile }，Profile必须是导出类型（首字母大写），不能是profile或map[string]interface{} - 数组字段如
Users []User，在@Success中必须写{array}User，不能只写User
Swagger UI 打开空白或 404？gin 路由注册顺序错了
gin-swagger 是个中间件，它匹配 /swagger/*any 路径，但 Gin 的路由匹配是顺序敏感的。挂载太早，会被前面的 router.NoRoute 或 panic 捕获逻辑拦截。
Golang Spf13 Viper
下载
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
立即学习“go语言免费学习笔记（深入）”；
- 必须在所有业务路由注册完之后、
r.Run()之前调用：r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler)) - 不能在
r := gin.New()后立刻挂载 swagger —— 此时默认中间件（logger/recovery）还没启用，panic 会导致整个服务不可用 -
/swagger/*any中的*any是 Gin 特有通配符，写成/swagger/或/swagger/*都无法命中子资源（如/swagger/index.html） - 如果用了
r.Group("/api/v1")，swagger 路由仍要挂在根 router 上，不要放进 group
每次改完注释文档不更新？缓存和生成流程被忽略
浏览器缓存、本地 docs 包未重载、swag init 未重新执行 —— 这三个环节任何一个断掉，看到的都是旧文档。
- 每次修改
@Param、@Success或结构体后，必须重新运行swag init，它会覆盖docs/docs.go - Go 程序启动时会 import
_ "your-project/docs"，这个包必须重新编译才能生效；删掉docs目录再swag init更保险 - 浏览器访问
/swagger/index.html时，强制刷新（Ctrl+Shift+R）或禁用缓存，避免加载旧 JS/CSS - 不要手动编辑
docs/swagger.json—— 它是自动生成的，下次swag init会被覆盖
真正卡住人的从来不是命令敲不对，而是注释里一个空行、结构体少一个大写字母、或者 swag init 多跑了一次却没清掉旧 docs 包 —— 这些细节没有报错，但文档就永远停在上一版。
