api-generating
npx machina-cli add skill huangjia2019/claude-code-engineering/api-generating --openclawAPI 文档生成 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
Source
git clone https://github.com/huangjia2019/claude-code-engineering/blob/main/04-Skills/projects/06-agent-skill-combo/.claude/skills/api-generating/SKILL.mdView on GitHub Overview
Generates API endpoint documentation directly from Express route files. It uses a Python-based route discovery process, analyzes HTTP method, path, parameters, and schemas, and renders docs from a template. Auth and validation requirements are detected and clearly marked to keep docs in sync with code.
How This Skill Works
Step 1: Discover routes by running the Python script: python3 skills/scripts/detect-routes.py src/. Step 2: For each route, read the handler source to capture method, path, params, request/response schemas, and any authentication or validation middleware. Step 3: Generate docs from templates/api-doc.md, producing one markdown file per route group (e.g., docs/api/users.md) with examples and 🔒 marks for authenticated endpoints.
When to Use It
- You need to generate API docs from new Express route files.
- Routes have changed and you want to update the documentation to reflect updates.
- You want to review existing API docs for accuracy against the actual code.
- You’re onboarding new developers and require up-to-date API references.
- You’re preparing client-facing API docs or SDK references and need consistent formatting.
Quick Start
- Step 1: Run route discovery: python3 skills/scripts/detect-routes.py src/
- Step 2: Let the script analyze each route (method, path, params, auth, validation) and prepare data.
- Step 3: Generate docs with templates/api-doc.md; inspect docs/api/ for per-group markdown files.
Best Practices
- Always start with the route discovery step to catch edge cases like dynamic routes and sub-routers.
- Cross-check route details (method, path, params, request/response schemas) against the source.
- Clearly indicate auth/validation requirements and include how to authenticate where applicable.
- Use the templates/api-doc.md to ensure consistent structure and helpful examples.
- Include valid JSON examples and place docs in a per-route-group file under docs/api/ (e.g., docs/api/users.md).
Example Use Cases
- docs/api/users.md documenting GET /users, POST /users, and GET /users/:id with auth where required.
- docs/api/products.md covering GET /products, GET /products/:id, and POST /products with validation.
- docs/api/auth.md detailing POST /login and POST /logout with example responses.
- docs/api/orders.md for POST /orders and GET /orders/:id with request/response schemas.
- docs/api/admin.md showing protected endpoints like GET /admin/stats marked with 🔒.
