真正能落地的 Swagger 文档方案是将生成嵌入 CI/CD 并与代码强绑定；swag init 报错“failed to scan directory”主因是未用 -d 指定含 // @title 的模块路径，且需注意 swaggerignore:"true" 等大小写规范、docs 目录需 mkdir -p 预创建并校验 swagger.json 非空。
Go 微服务接口变更后，手写 Swagger 文档或靠人工同步注释极易出错、滞后，真正能落地的方案是把文档生成嵌入到 CI/CD 流程中，且必须和代码定义强绑定——否则改了 Handler 却漏掉 @Param 注释，生成的文档就是错的。
用 swag CLI 生成 docs 时为什么总报错 “failed to scan directory”
根本原因是 swag init 默认只扫描当前目录下带 // @title 的 Go 文件，而微服务通常按模块拆分（如 internal/handler、pkg/api），如果没显式指定路径，它就扫不到你的路由文件。
- 执行前确认主入口文件（如
main.go）里有完整的 Swagger 元信息注释，至少包含// @title、// @version - 用
-d指定根目录，比如服务入口在cmd/myapp/main.go，但 handler 在internal/handler，就得运行：swag init -d ./internal/handler -g ../cmd/myapp/main.go
- 避免在
go mod子模块里调用swag init—— 它不识别replace或require中的本地路径，会直接跳过依赖包里的 API 注释
struct 字段 tag 里加 swagger:ignore 不生效
Swag 解析结构体时默认只看 json tag，swagger tag 需要额外声明。常见误区是以为写成 swagger:"ignore" 就能跳过字段，其实 swag 要求的是 swaggertype 或 swaggerignore（注意拼写和大小写）。
Golang Spf13 Viper
下载
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
- 忽略字段用
swaggerignore:"true"，例如：type UserReq struct { ID int `json:"id"` Name string `json:"name" swaggerignore:"true"` } - 若字段类型无法被 swag 自动推导（如自定义 time 类型），需显式声明
swaggertype，例如：CreatedAt time.Time `json:"created_at" swaggertype:"string" format:"date-time"`
- 别在嵌套 struct 上漏掉顶层 tag —— swag 不递归解析未导出字段，所有要暴露的字段名首字母必须大写
CI 中自动生成 docs 并推送到 gh-pages 失败，提示 “docs folder not found”
swag init 默认输出到 docs/ 目录，但很多 CI 脚本假设该目录已存在或被 git 跟踪，而实际上 docs/ 是生成物，不应进仓库，CI 运行时它是空的甚至不存在。
立即学习“go语言免费学习笔记（深入）”；
- 在 CI 脚本里先确保目标目录可写：
mkdir -p docs
- 生成后检查
docs/swagger.json是否真实生成（不是空文件），swag 出错时可能静默创建空目录；建议加校验：test -s docs/swagger.json || (echo "swagger.json is empty" && exit 1)
- 推送到 gh-pages 时，不要用
git add .，而是精确提交：git add --force docs/ && git commit -m "chore: update API docs"
，否则容易误提交其他临时文件
最难绷的其实是跨服务复用 model：一个 User struct 在 auth 服务里加了 swaggerignore，但在 user 服务里又需要暴露，这种场景没法靠全局配置解决，只能靠代码层隔离 —— 每个服务维护自己的 API struct 副本，哪怕字段一样。别省这点复制粘贴。
