Go项目接口文档与SDK自动同步需以swagger.json为唯一事实源，串联文档生成与SDK生成流水线；用openapi-generator基于该JSON生成客户端，CI校验其变更并强制提交SDK代码，确保全链路可信同步。
Go 项目里接口文档和客户端 SDK 要真正自动同步，靠单点工具（比如只用 swag）根本做不到——它只管生成 swagger.json，不碰 SDK。必须把「文档生成」和「SDK 生成」两个环节串成一条流水线，且共用同一份源数据。
swag init 生成的 swagger.json 是唯一可信源
所有后续动作（UI 渲染、SDK 生成、Mock 服务）都必须基于 docs/swagger.json，而不是反向从 Go 代码解析。原因很实在：
-
swag的注释解析能力有限，@Param user body model.User中的model.User如果没加// @Model或字段没导出+无json:tag，就会丢字段；但一旦swagger.json生成成功，它的 schema 就是当前代码的真实快照 - 第三方 SDK 生成器（如
openapi-generator）只认 OpenAPI 文件，不认 Go 源码；强行绕过 JSON 直接读 Go AST，会重复踩swag已经填过的坑（类型别名、嵌套泛型、中间件注入参数等） - CI/CD 中只要校验
swagger.json是否变更，就能触发下游 SDK 构建，逻辑清晰，无歧义
用 openapi-generator CLI 生成 Go 客户端 SDK
别写脚本拼接命令，直接用官方 CLI，稳定且支持全语言。关键不是“能不能生成”，而是“生成后能不能直接用”：
- 安装：
brew install openapi-generator（macOS）或下载二进制，确保版本 ≥ 7.0.1（对 OpenAPI 3.0.3 支持更稳） - 生成命令必须带
--additional-properties=withGoCodegenComment=true，否则生成的 client 方法里没有// @Summary原文注释，前端查起来费劲 - 指定输出路径时用绝对路径，避免相对路径在 CI 中因工作目录不同导致写错位置：
openapi-generator generate -i $(pwd)/docs/swagger.json -g go -o /tmp/myapi-sdk --additional-properties=... - 生成后立刻跑
go mod tidy && go build ./...，验证是否因引用了未导出 struct 或缺失json:tag 导致编译失败——这是最硬的验收标准
gin-swagger UI 和 SDK 之间必须共享同一份 docs/ 目录
很多人把 docs/ 放在 cmd/ 下，结果 SDK 生成器读不到，或者 Swagger UI 加载 404。真实项目结构应该这样安排：
立即学习“go语言免费学习笔记（深入）”；
-
docs/swagger.json和docs/swagger.yaml（可选）放在项目根目录，和go.mod同级 - Gin 项目中注册 Swagger UI 时，静态文件路径必须指向这个根目录下的
docs：swaggerFiles.Handler(swaggerFiles.Config{DeepPrefix: "/swagger"})，且启动前确认docs/已存在并可读 - SDK 生成脚本也从同一路径读取：
-i ./docs/swagger.json，不依赖环境变量或配置项传路径 - 如果用 GoFrame 或 go-zero，它们内置的文档服务也默认读取根目录
docs/，不用额外映射
SDK 更新必须触发 git commit，否则同步就失效
自动生成不等于自动发布。最容易被忽略的是：SDK 代码生成后，必须作为正式代码提交进仓库，否则其他服务调用时仍用旧版 client，接口一改就 panic。
- 写一个
make sdk目标，内部执行swag init && openapi-generator generate ... && go fmt ./sdk && git add ./sdk - 在 CI 流程中，仅当
swagger.jsondiff 不为空时才运行 SDK 生成，并强制要求该次 commit 包含sdk/目录变更，否则流水线失败 - 禁止在
go.mod中 replace 到本地 SDK 路径——这会让依赖方绕过版本控制，失去同步意义
真正的难点不在工具链拼接，而在于守住「单一事实源」：所有人（前端、测试、下游服务）只信任 docs/swagger.json，所有自动化流程都围绕它展开。一旦有人想绕过 JSON 直接读代码生成 SDK，整条同步链就断了。
