All endpoints documented

Severity: Recommended

Check automatically:

1. Look for API documentation:

   # OpenAPI/Swagger files
   find . -type f \( -name "openapi*.yaml" -o -name "openapi*.json" -o -name "swagger*.yaml" -o -name "swagger*.json" \) \
     -not -path "*/node_modules/*" 2>/dev/null
   
   # Check for API docs in docs folder
   find . -type f -name "*.md" -path "*/docs/*" 2>/dev/null | xargs grep -li "endpoint\|api\|route" 2>/dev/null
   

2. Find all route definitions in code:

   # Express/Node patterns
   grep -rn "app\.\(get\|post\|put\|patch\|delete\)\|router\.\(get\|post\|put\|patch\|delete\)" \
     --include="*.ts" --include="*.js" . 2>/dev/null | grep -v node_modules | head -30
   
   # Next.js API routes
   find . -type f -path "*/api/*" \( -name "*.ts" -o -name "*.js" \) -not -path "*/node_modules/*" 2>/dev/null
   

3. Check if docs are exposed in production:

   # Look for Swagger UI routes
   grep -rn "swagger-ui\|/api-docs\|/docs\|/swagger" --include="*.ts" --include="*.js" . 2>/dev/null | grep -v node_modules
   
   # Check if gated by environment
   grep -rn "swagger\|api-docs" --include="*.ts" --include="*.js" . 2>/dev/null | grep -i "NODE_ENV\|production\|isDev"
   

4. Cross-reference: Compare documented endpoints against actual routes in code

Pass criteria:

• API documentation exists (OpenAPI, Swagger, or markdown)
• Documentation covers all routes found in code
• Docs endpoint disabled in production OR project intentionally exposes public API docs

Fail criteria:

• No endpoint documentation
• Documentation exists but is incomplete (missing endpoints)
• Swagger UI / docs endpoint exposed in production without intentional reason

If no formal docs, ask user: "No OpenAPI/Swagger found. Are endpoints documented elsewhere? How do consumers know what's available?"

If docs exposed in production, ask user: "API docs appear accessible in production (/api-docs, /swagger). Is this intentional? For internal APIs, docs should be dev-only."

Evidence to capture:

• Documentation location (file path or URL)
• Count: documented endpoints vs actual endpoints in code
• Whether docs are production-accessible (and if intentional)

---