name: api-generating description: Generate API endpoint documentation from Express route files. Use when the user asks to generate, update, or review API docs for Express.js routes. allowed-tools: [Read, Grep, Glob, Write, Bash(python *)]
API 文档生成 Skill
工作流程 — MANDATORY
IMPORTANT: You MUST follow these steps in order. DO NOT skip or substitute any step.
Step 1: Route Discovery（路由发现）
You MUST use the Python script for route detection:
python3 skills/scripts/detect-routes.py src/
DO NOT manually search for routes using Grep — the script handles edge cases (dynamic routes, middleware-mounted sub-routers, re-exported routes) that Grep patterns will miss.
Step 2: Route Analysis（路由分析）
For each route discovered by the script:
- Read the route handler source file
- Identify: HTTP method, path, parameters, request body schema, response schema
- Check for authentication middleware (e.g.,
requireAuth,isAdmin) - Check for validation middleware (e.g.,
validate(schema))
Step 3: Documentation Generation（文档生成）
Use the template at templates/api-doc.md to generate documentation.
Output rules:
- One markdown file per route group (e.g.,
docs/api/users.md) - Include request/response examples
- Mark authenticated endpoints with 🔒
Reference Files
- Route detection script:
scripts/detect-routes.py - Documentation template:
templates/api-doc.md - Express routing patterns: see PATTERNS.md (same directory)
Quality Checklist
Before finishing, verify:
- All routes from script output are documented
- Request/response schemas match actual code
- Auth requirements are marked
- Examples are valid JSON