Agent Skills
返回列表
💻

Swagger 生成器

开发编程 更新于 2026.08.30

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

请根据 https://skillhub.cn/install/skillhub.md,安装 @org-eyw2ohcx/sundial-org-awesome-openclaw-skills-swagger-gen。

技能介绍

问题从哪来

Express 项目路由往往散落在多个文件里,接口一多就没人愿意手搓 OpenAPI:字段类型要对齐 handler、路径和方法要对上实现,稍有遗漏 Swagger UI 就和真实行为不一致。团队对外没文档时,对接方只能翻源码或靠口头约定,排错和联调成本都堆在维护者身上。

技能在做什么

该技能围绕 Swagger Generator 的工作方式组织说明:工具会解析 Express 路由定义,抽出 endpoint、HTTP 方法以及与之关联的 handler 逻辑,再据此生成符合 OpenAPI 3.0 的规范,并尽量把请求/响应形状写进 spec,便于直接挂 Swagger UI 或给消费方做契约参考。

典型关注点包括:

  • 零配置起步:强调一条命令、通过 npx 运行,不必先搭一套文档流水线(SKILL.md 写明 Node.js 18+,且需 OPENAI_API_KEY 环境变量)。
  • 与路由同频:路由变更后应重新生成,避免文档漂移。
  • 可维护性:在生成结果上补 endpoint 描述、示例请求,以及非 2xx 的错误响应,而不只写 happy path。

适用边界

它面向 Express 栈里「已有路由、缺规范」的场景,不能替代你手写业务语义极复杂的 schema;若项目不用 Express 或路由风格难以静态解析,生成质量会受限。生成物是起点,上线前仍建议人工核对关键接口与鉴权、分页等约定。

使用场景

  • Express 微服务要对外提供接口清单,但仓库里只有路由文件、没有可分享的 OpenAPI
  • 新同事接入内部 REST API,需要先把现有路由收成一份可浏览的 Swagger 规范
  • 版本发布前要把本次改动的 endpoint 同步进文档站,避免 Swagger UI 与实现不一致
  • API-first 迭代中想用生成 spec 作为评审材料,再人工补描述与错误码

适合人员

  • 维护 Express 单体或 BFF、对接方反复索要接口说明的后端工程师
  • 负责开发者体验、要把零散路由整理成统一 API 门户的技术写作者
  • 带外包或合作方联调、需要可交付 OpenAPI 契约的技术负责人
  • 从遗留 Express 项目抽出文档、准备接入 Swagger UI 的全栈开发者