新项目应选OpenAPI 3.0——它原生支持oneOf、anyOf、nullable及细粒度schema复用，对微服务多态响应建模更自然；若需对接老系统，须用openapi-generator-cli转换而非swag自带参数，因后者仅改version字段而不重写结构。
用 Swagger 2.0 还是 OpenAPI 3.0？
Go 生态里主流的 API 文档生成方案（如 swag、go-swagger）默认输出 OpenAPI 3.0，但很多旧版网关、mock 工具或 CI/CD 插件只认 Swagger 2.0。别等上线才发现 400 Bad Request 来自文档格式不兼容。
实操建议：
- 新项目直接选 OpenAPI 3.0——它原生支持
oneOf、anyOf、nullable和更细粒度的 schema 复用，对微服务间多态响应建模更自然 - 如果必须对接老系统，用
swag init -o swagger.json --quiet生成后，再用官方转换工具openapi-generator-cli convert -i swagger.yaml -o converted/转成 2.0，别依赖 swag 自带的--swagger-version参数，它只改 version 字段，不重写结构 - 所有
@success注释里的 status code 必须显式写全，比如// @Success 200 {object} model.User，漏掉200会导致 OpenAPI 3.0 的responses里缺失 key，生成的 client 会 panic
如何让 struct 标签自动映射到 OpenAPI schema？
Go 的 struct tag 是文档可扩展性的核心杠杆。光靠 json: 标签不够，OpenAPI 需要描述字段是否必填、范围、示例、弃用状态——这些得靠额外标签注入。
实操建议：
- 统一用
swaggertype:+swaggerignore:控制字段可见性，比如CreatedAt time.Time `json:"created_at" swaggertype:"string" format:"date-time"`，否则time.Time会被当成 object 导出，前端解析失败 - 嵌套 struct 不要直接匿名内嵌，哪怕只是
BaseResponse，也得显式命名字段并加swaggerignore:"true"，否则 swag 会把内嵌字段全部 flatten 到当前 schema，破坏边界契约 - 枚举值必须用
enums:tag 显式声明，Status string `json:"status" enums:"pending,done,failed"`，否则 OpenAPI 里只剩string类型，Swagger UI 不会渲染下拉菜单
多个微服务共用一套文档时怎么避免 schema 冲突？
当 user-service 和 order-service 都定义了 User struct，但字段不同，直接合并 swagger.json 会导致 schema 名冲突，OpenAPI validator 直接报错 duplicate definition。
实操建议：
- 每个服务在
swag init时加--parseDependency，但禁止跨服务 import struct——哪怕只是想复用model.User，也要在本地重新定义，用// @name UserV1注释覆盖 schema 名 - 用
x-tagGroups扩展字段按业务域分组，比如在docs/swagger.go顶部加// @x-tagGroups [{"name":"User","tags":["user"]}]，这样聚合文档时能隔离操作域 - CI 流程里加校验步骤：
jq '.components.schemas | keys | length' docs/swagger.json，单个服务文档 schema 数超过 50 个就要警觉——大概率混入了不该暴露的 internal struct
文档变更如何触发下游 SDK 自动更新？
手动生成 client SDK 容易过期，尤其当 proto-first 或 contract-first 流程缺失时，API 变更和 SDK 发布之间常有数小时 gap，导致调用方 panic。
实操建议：
- 用
openapi-generator-cli generate -i docs/swagger.json -g go -o ./client --git-user-id your-org --git-repo-id go-client，关键在--git-repo-id，它让生成器把 SDK 推到指定 repo，配合 GitHub Action 监听docs/swagger.json变更即可触发发布 - 禁止在 client 代码里手动修改 generated 文件——所有定制需求（如超时、重试）通过 wrapper 层实现，否则下次生成会覆盖
- 给生成的 client 加
// Code generated by openapi-generator. DO NOT EDIT.头注释，并在 CI 中用grep -q "DO NOT EDIT" client/api.go检查是否被篡改
schema 命名冲突和 tag 控制粒度，是多数团队卡住的地方。别指望 swag 自动推断业务语义，每个 swaggertype 和 enums 都得人肉对齐领域模型。
