Agent Skills
返回列表
💻

Swagger Codegen 模板自定义器

开发编程 更新于 2026.08.29

将以下提示词粘贴到你的 AI 对话框中：

请根据 https://skillhub.cn/install/skillhub.md，安装 @user_3c6cb52e/swagger-codegen-template-customizer。

技能介绍

解决什么问题

规范定稿之后，团队通常要为多种语言维护客户端 SDK。Swagger Codegen 与 OpenAPI Generator 能依据 OpenAPI 规范批量生成代码，但默认模板的产物往往需要二次加工：包名不符合项目约定、错误处理风格与既有代码不一致、返回类型命名和团队规范冲突。每次规范升级或更换生成器，这些改动都要重来一遍。

这个技能把模板定制变成一次可复用的操作：在生成阶段注入自定义 Mustache 模板，直接控制产物的结构与命名，而不是生成之后再打补丁。

核心能力

  • 模板注入：基于 Mustache 语法编写模板，作用于生成流程本身，可以调整生成代码的组织方式与命名风格
  • 多语言输出：覆盖三类常见客户端目标：

- Java：OkHttp / Retrofit
- TypeScript：Axios / Fetch
- Python：httpx

  • 与上游工具协同：作为 Swagger Codegen 与 OpenAPI Generator 的扩展层使用，模板按生成器的模板目录约定放置

典型流程

  1. 编写或修改 Mustache 模板，覆盖需要定制的输出片段
  2. 将模板接入生成流程，选定目标语言与 HTTP 库组合
  3. 运行生成器，得到符合团队约定的 SDK 代码
  4. 在 CI 中固定模板版本，保证多次生成结果一致

适用边界

  • 模板只控制生成产物的形态，不改变生成器对规范的解析逻辑；规范本身的问题仍会反映到产物中
  • 定制效果依赖对 Mustache 语法和目标生成器模板目录的理解，建议先在少量接口上验证再全量应用
  • 上游生成器版本升级时，模板可能需要同步调整，应将模板纳入版本管理
  • 上游文档提到 SwaggerUI 会通过 Scarf 收集匿名安装统计；如果部署环境对遥测有要求，需要提前确认相关配置

使用场景

  • 团队使用 OpenAPI Generator，需要为 Java 接口统一生成 Retrofit 客户端代码。
  • 前端需要基于规范生成 Axios 封装，接口路径与返回类型命名需符合团队规范。
  • 后端为 Python 服务生成 httpx 客户端，要求统一异常处理与响应对象结构。
  • CI 流程中固定模板版本，确保多次生成的客户端 SDK 结构稳定一致。

适合人员

  • 负责多语言客户端 SDK 的工程师，希望规范生成产物符合项目命名与结构约定。
  • 维护 API 生成流程的技术负责人，需要把模板定制纳入版本管理与 CI。
  • 前后端协作团队的开发者，希望接口产物风格统一，减少生成后手工修改。
  • 为内部服务生成 Python httpx 客户端的后端工程师，要求返回结构稳定。