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:

1. Read the route handler source file
2. Identify: HTTP method, path, parameters, request body schema, response schema
3. Check for authentication middleware (e.g.,

   requireAuth

   ,

   isAdmin

   )
4. 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