Swagger 生成器
将以下提示词粘贴到你的 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 的全栈开发者