技能介绍

解决什么问题

当 API 以 OpenAPI 3.x 文档作为事实来源时，前端、后端和平台团队常常需要同时维护 TypeScript、Python、Go 三套客户端。手写 SDK 会随接口演进产生漂移：参数命名不一致、错误模型缺失、请求重试和鉴权逻辑重复实现，联调时还要反复确认字段含义。Swagger Codegen Orchestrator 把代码生成收敛到统一流程，用 swagger-codegen-cli 或 openapi-generator 从同一份 spec 产出类型化客户端，避免“文档改了、代码没改”的常见问题。

技能如何工作

核心能力是编排，而不是替代上游生成器。它的输入是 OpenAPI 3.x 文档和生成目标；执行时选择 swagger-codegen-cli 或 openapi-generator，把语言目标、输出目录、包名、类名等参数交给生成器处理，并接入自定义 Mustache 模板。模板适合处理生成器的代码骨架，例如让 TypeScript 客户端导出更符合团队习惯的类型与函数，让 Python 包结构更贴近现有仓库布局，或让 Go 客户端的命名、注释和 import 更可读。

关键步骤可以按工程习惯拆成：确认 spec 的 operationId、schema、错误码和安全方案足够完整；为每种目标语言准备生成配置；把自定义模板放在生成器可读取的位置；执行生成；用构建与测试验证产物；最后把生成物纳入版本控制或 CI 校验。这样得到的客户端应尽量保持与接口契约一致。

适用边界与注意点

它适用于 OpenAPI 3.x 场景，尤其是需要多语言 SDK、已有生成器工具链、并且愿意用模板约束输出风格的团队。生成质量仍然依赖 spec 本身：字段描述缺失、枚举不稳定、鉴权方案模糊，都会直接传导到产物中。自定义 Mustache 模板与生成器版本绑定较紧，升级 swagger-codegen-cli 或 openapi-generator 时需要复查模板变量和输出结构。不要把这个技能当作接口校验器；契约审查、兼容性测试和运行时行为仍应单独覆盖。