OpenAPI Generator 生成的 Go 客户端不包含自动鉴权逻辑，仅在注释中提示如 // Bearer token authentication，需手动设置 client.GetConfig().DefaultHeader["Authorization"] = "Bearer " + token，且 token 刷新需自行封装 HTTP 中间件或劫持 Transport。
openapi-generator generate -g go 生成的 client 为什么没带鉴权逻辑
因为 OpenAPI Generator 不会自动注入认证头——它只读 securitySchemes 并加注释，不写实际代码。你看到的 // Bearer token authentication 是提示，不是实现。
常见错误现象：调用生成的 APIClient.SomeEndpoint() 返回 401，但 config.DefaultHeader 没被赋值；或者用了 withGoCodegenV2=true 却发现 Authorization 字段根本没出现在 struct tag 里。
- 必须手动设置：
client := NewAPIClient(config.NewConfiguration())后立刻执行client.GetConfig().DefaultHeader["Authorization"] = "Bearer " + token - 如果 token 会刷新（比如 OAuth2），不能只设一次，得包装一层
Do()或用中间件劫持http.Client.Transport -
securitySchemes类型为apiKey时，生成器默认往header放，但字段名未必是Authorization（比如X-Api-Key），要对照 spec 里的name字段来设 key
oapi-codegen 和 openapi-generator 的 client 生成差异在哪
核心区别在 HTTP 层控制粒度：oapi-codegen 默认输出裸函数（如 GetUsers(ctx, client, params)），直接复用你传入的 *http.Client；而 openapi-generator 生成的是带状态的 APIClient 实例，内部硬编码了 http.DefaultClient，改起来更重。
使用场景决定选谁：
立即学习“go语言免费学习笔记（深入）”；
- 项目已用
oapi-codegen生成 server 端代码（比如 Huma/Goa），客户端统一用它，避免两套 schema 解析逻辑 - 需要插
otelhttp.RoundTripper、retryablehttp.Client或自定义context.WithTimeout，oapi-codegen更直接——你传啥 client 它就用啥 - 团队要快速上手、接受“标准 SDK 风格”，选
openapi-generator；它生成的Configuration结构体、APIClient方法命名都更接近 Java/Python SDK 的直觉 - 两者都不支持生成带自动 token 刷新的 client，别指望
-g go或-generate client能帮你处理refresh_token流程
openapi.yaml 格式不合法导致 generate 失败的典型报错
报错信息像 Unable to read/open input document 或 missing required field 'openapi'，基本等于文档没过 OpenAPI 3.1 基础校验——不是工具问题，是输入不对。
最容易漏检的三处：
-
openapi: 3.1.0字段缺失或写成3.0.3（oapi-codegen要求严格 3.1，openapi-generator对 3.0.x 兼容但部分新特性不认） -
components.schemas.User定义了，但某个requestBody里写的是$ref: '#/components/schema/User'（少了个s），校验器静默失败，生成器却崩 - Postman 导出的
collection.json直接当-i输入，结果生成一堆空struct{}—— Postman collection 不是 OpenAPI，必须先转，可用 openapi-to-postman 反向转换，或用 Swagger Editor 粘贴后导出 YAML
验证命令必须跑一遍：openapi-generator validate -i openapi.yaml，别跳。
生成后必须补的三处 glue code
生成代码只是骨架，不补这三块，99% 的生产环境会出问题：
-
HTTP 客户端超时：
openapi-generator默认用http.DefaultClient，没有 timeout；oapi-codegen虽然让你传*http.Client，但没人帮你 new 一个带Timeout: 30 * time.Second的实例 -
Base URL 动态化：生成的 client 通常把
server.url写死在 config 里（如"https://api.example.com/v1"），但测试/灰度环境需要切换，得暴露可配置字段，而不是改生成代码 -
错误分类处理：生成器只返回
error，但真实场景要区分网络错误、4xx 业务错误、5xx 服务错误——得自己封装if err != nil { if apiErr, ok := err.(APIError); ok { ... } }这类逻辑
这些不是“锦上添花”，是上线前必须手写的最小可行集。别信“开箱即用”，OpenAPI 工具链里没有银弹。
