用途
swagger-gen 旨在解决 API 缺少文档的问题,它通过读取 Express 路由文件,自动生成完整的 OpenAPI 3.0 规范,适合需要为接口补充文档的场景。
主要能力
- 读取 Express 路由文件
- 生成 OpenAPI 3.0 规范
- 记录请求与响应的数据结构
- 生成的规范可直接用于 Swagger UI
使用方式
该工具通过 npx 运行,无需预先安装。推荐 Node.js 18+ 环境,并且需要设置 OPENAI_API_KEY 环境变量。
生成整个路由目录的规范:
npx ai-swagger ./src/routes/
针对单个文件并指定输出路径:
npx ai-swagger ./src/routes/users.ts -o docs/api.yaml
查看帮助:
npx ai-swagger --help
适用场景
- 创建 API 文档
- 搭建 Swagger UI
- 帮助 API 使用者快速上手
- API 优先设计流程
限制与注意事项
资料未提供关于收费、价格或具体效果保证的信息。工具本身为免费使用(MIT 许可),但需要 OPENAI_API_KEY 环境变量,且相关 API 调用的费用情况资料未提供。建议在路由变更后重新生成文档,并补充描述、示例和错误说明以提升文档质量。