openapi spec 是生成 sdk 的前提，必须先将 api 定义收敛为符合 openapi 3.1 的 yaml/json；推荐用 swagger-editor 校验，后端为 go 时可用 swag 自动生成；openapi-generator 适合多语言同步与开箱即用，oapi-codegen 更轻量且利于 http 层深度定制；两者均需手动补全 base url、认证头和错误处理，并严格对齐 go module 路径。
OpenAPI Spec 是生成 SDK 的前提，不是写完代码再补文档
Go 语言本身不内置 SDK 生成能力，所有可靠方案都依赖 OpenAPI（即 Swagger）规范。如果你手头只有接口文档 PDF、Postman 集合或裸 HTTP 请求示例，openapi-generator 或 oapi-codegen 都无法工作——它们读的是 openapi.yaml 或 openapi.json，不是人话描述。
常见错误现象：openapi-generator generate -i api.docx -g go 报错 Unable to read URL or file: api.docx；或者用 Postman 导出的 collection.json 直接喂给生成器，结果生成出一堆空 struct 和无意义方法。
- 必须先将 API 定义收敛为符合 OpenAPI 3.1 的 YAML/JSON
- 推荐用
swagger-editor实时校验语法，尤其注意components.schemas是否定义完整、requestBody.content."application/json".schema是否指向有效 ref - 如果后端是 Go 写的，用
swag（配合// @Success 200 {object} User注释）可自动生成 spec，比手写靠谱得多
openapi-generator 和 oapi-codegen 选哪个？看你的 HTTP 客户端偏好
openapi-generator 生成带 net/http 底层封装的客户端，结构清晰、可调试性强；oapi-codegen 默认绑定 go-swagger 风格 client，但更轻量，且能复用已有的 http.Client 实例（比如你已经配好了 retry、timeout、metrics）。
实操建议：
- 要开箱即用、支持多语言同步（比如同时生成 Python/JS SDK），用
openapi-generator：openapi-generator generate -i openapi.yaml -g go -o ./sdk --package-name apisdk
- 要深度控制 HTTP 层（如插入
otelhttp.Transport、自定义context.WithTimeout）、或项目已用oapi-codegen做 server 端代码生成，就统一用它：oapi-codegen -generate types,client openapi.yaml > sdk/client.go
- 两者都不支持直接生成带 OAuth2 token 自动刷新逻辑的 client，这类逻辑必须手写 wrapper —— 别指望生成器替你处理
refresh_token流程
生成的 client 不是“扔进去就能用”，必须补三处关键 glue code
无论用哪种工具，生成的代码只是骨架：没有 base URL、没有认证头、没有错误分类处理。直接调用 client.GetUser(ctx, id) 十有八九 panic 或返回 401。
- Base URL 必须显式传入构造函数（
openapi-generator生成的 client 通常叫NewAPIClient，第一个参数是Configuration，其中含BasePath） - 认证头需手动注入：比如 Bearer Token，得在每次请求前调用
client.SetConfig(&config{...})或用 middleware 包装http.Client（oapi-codegen更倾向后者） - 错误处理不能只看
err != nil：HTTP status 400–499 多数返回非 nilerr，但 5xx 有时只返回nil err + non-2xx *http.Response，得检查resp.StatusCode
别忽略 Go module 路径和 vendor 兼容性问题
生成的 SDK 默认用相对导入（如 import "./models"）或硬编码模块路径（如 import "github.com/yourorg/yourapi/sdk/models"）。如果 SDK 要作为独立 module 提供给其他团队，go mod init 的路径必须和 import 路径一致，否则 go build 报 cannot find module providing package。
容易踩的坑：
- 用
openapi-generator时加--additional-properties=packageName=apisdk,module=github.com/yourorg/yourapi/sdk显式指定 - 用
oapi-codegen生成时，确保go.mod已存在且module行与生成目标目录匹配，否则生成的import语句会错位 - 如果下游项目用了
vendor，生成的 SDK 里所有import "github.com/..."必须能在 vendor 目录下找到，否则go build -mod=vendor失败
生成 SDK 看似一步命令，真正卡住人的永远是 OpenAPI 规范质量、HTTP 客户端定制粒度、以及 module 路径和实际工程结构的对齐——这三块不提前对齐，生成出来的代码越“全自动”，后期修起来越费劲。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
