构建Golang微服务的自动化接口变更文档-Golang-PHP中文网

真正能落地的 swagger 文档方案是将生成嵌入 ci/cd 并与代码强绑定；swag init 报错“failed to scan directory”主因是未用 -d 指定含 // @title 的模块路径，且需注意 swaggerignore:"true" 等大小写规范、docs 目录需 mkdir -p 预创建并校验 swagger.json 非空。

构建golang微服务的自动化接口变更文档

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 运行时它是空的甚至不存在。

在 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 副本，哪怕字段一样。别省这点复制粘贴。