用途:为已有的 Next.js App Router 项目生成 OpenAPI 3.1 接口文档,适合需要补全 API 文档、创建 OpenAPI 规范或梳理端点的场景。生成前会读取 config/defaults.md,并按用户配置的技术栈调整模式、导入与代码示例。
主要能力:扫描 app/api/ 目录下所有 route.ts 文件;提取导出的 HTTP 方法处理器(GET、POST、PUT、PATCH、DELETE)、由文件路径推导的 URL 路径、请求与响应类型、Zod schema、中间件与鉴权模式;将 Next.js 路径转换为 OpenAPI 路径,例如 app/api/users/[id]/route.ts 转为 /api/users/{id},catch-all 路由 app/api/[...slug]/route.ts 转为 /api/{slug};优先从 Zod schema 提取结构,无 Zod 时从 TypeScript 类型注解推断;识别常见鉴权模式并添加安全方案,如 session 检查对应 Bearer 或 cookie 会话、x-api-key 请求头对应 API key;扫描 NextResponse.json 调用及状态码构建响应 schema;识别分页参数(page、limit、offset、cursor)、文件上传(request.formData() 对应 multipart/form-data),并抽取统一错误响应格式为可复用组件。
使用方式:在 Next.js 项目中调用该技能,默认输出 YAML,也可要求输出 JSON,生成文件为 openapi.yaml 或 openapi.json,并附带端点数量、schema 数量与端点汇总表。
限制:仅面向 Next.js App Router 的 app/api/ 路由;鉴权与响应结构依赖代码中的可识别模式,无法识别的写法可能无法完整提取;资料未提供具体安装命令、收费方式与平台支持信息。