用途
OpenAPI Endpoint Documentation Lab 是 Recollect 项目中的一个技能，用于端到端地生成和维护 OpenAPI 端点文档。它通过自主执行六个阶段，确保 API 文档的完整性和准确性。该技能适用于需要为 API 端点生成高质量文档的开发者，特别是使用 Zod 和 OpenAPI 的 TypeScript 项目。
主要能力
该技能能够自主发现路由处理器，识别工厂类型（如 createGetApiHandlerWithAuth、createPostApiHandlerWithAuth 等）、HTTP 方法、ROUTE 常量以及 schema 来源。它审计 Zod schema，确保每个字段都有 .meta({ description: "..." })，以便在生成的 OpenAPI 规范中显示字段描述。技能还创建补充文件，包含路径、方法、标签、摘要、描述、安全要求以及请求/响应示例。补充文件支持命名示例、错误示例和参数示例。此外，技能通过桶导出自动注册补充文件，并验证规范生成和 UI 渲染。
使用方式
技能执行一个循环：发现 → Schema 审计 → 创建补充 → 桶导出 → 验证规范 → 验证 UI。如果任何验证失败，则修复并重试。具体步骤包括：
- 发现：使用 Glob 查找路由处理器和 schema 文件，读取域桶和同级补充文件以了解模式。
- Schema 审计：检查所有字段的 .meta()，添加缺失的描述，必要时将内联 schema 提取到 schema.ts。
- 创建补充：使用模板创建补充文件，填写路径、方法、标签、摘要、描述、安全要求以及示例。
- 桶导出：在域桶的 index.ts 中按字母顺序添加新导出。
- 验证规范：运行 npx tsx scripts/generate-openapi.ts 重新生成规范，检查输出行 Supplements applied: X/Y，并使用 jq 验证 JSON。
- 验证 UI：确保开发服务器运行，使用 Chrome MCP 导航到 http://localhost:3000/api-docs，检查端点是否出现、标签分组、示例渲染和字段描述。
适用场景
该技能适用于以下场景：
- 为新的 API 端点生成文档。
- 更新现有端点的 schema 或示例。
- 确保 API 文档的字段描述完整。
- 在 Scalar UI 中验证文档渲染效果。
限制
该技能要求项目使用特定的工厂函数和 Zod schema。边缘函数使用不同的工作流（手动 registerPath() 与原始 SchemaObject），需要参考 reference.md。补充文件路径必须相对于 /api，方法必须小写，标签必须大写。命名示例需要同时提供 summary 和 description。如果补充文件超过 250 行，应将示例提取到 <endpoint-name>-examples.ts 并使用 as const。常见错误包括路径错误、忘记 as const、使用单数示例而非命名示例、缺少 summary 或 description、忘记 .meta() 描述。