/api-docs

allowed-tools: Read, Write, Bash(fd:*), Bash(rg:*), Bash(jq:*), Bash(gdate:*), Task
name: "Api Docs"
description: "Generate comprehensive API documentation with OpenAPI specs and interactive sites"
author: "wcygan"
tags: ["docs","generate"]
version: "1.0.0"
created_at: "2025-07-14T00:00:00Z"
updated_at: "2025-07-14T00:00:00Z"

Context

• Session ID: !`gdate +%s%N 2>/dev/null || date +%s000000000 2>/dev/null || echo "1751900987850553000"`
• Current directory: !`pwd`
• Target: $ARGUMENTS
• Project structure: !`fd . -t d -d 2 | head -10 || echo "No subdirectories found"`
• API files: !`fd "\.(js|ts|go|rs|java|py|php|cs|rb|kt|scala)$" . | wc -l | tr -d ' ' || echo "0"`
• Route patterns: !`rg "(app|router|route)\.(get|post|put|delete|patch)" . --type js --type ts --type go --type rust | wc -l | tr -d ' ' || echo "0"`
• Controller files: !`fd "(controller|handler|route)" . -t f | head -5 || echo "No controllers found"`
• Existing docs: !`fd "(openapi|swagger)\.(json|yaml|yml)$" . | head -3 || echo "No existing API docs found"`
• Package files: !`fd "(package\.json|Cargo\.toml|go\.mod|pom\.xml|requirements\.txt)" . | head -3 || echo "No package files detected"`
• Framework indicators: !`rg "(express|fastify|axum|actix|gin|echo|spring|django|flask)" . --type js --type ts --type go --type rust --type java --type python | wc -l | tr -d ' ' || echo "0"`
• Git status: !`git status --porcelain | head -3 || echo "Not a git repository"`

Your Task

STEP 1: Initialize API documentation session

• CREATE session state file: `/tmp/api-docs-session-$SESSION_ID.json`
• SET initial state:

  {
    "sessionId": "$SESSION_ID",
    "phase": "discovery",
    "target": "$ARGUMENTS",
    "frameworks_detected": [],
    "endpoints_found": [],
    "documentation_strategy": "auto",
    "output_formats": []
  }

STEP 2: Determine documentation scope and strategy

Think hard about the optimal documentation approach based on project complexity and framework diversity.

**Extended Thinking Areas:**

• Framework detection strategies and confidence scoring algorithms
• Multi-language API schema extraction and synthesis approaches
• Interactive documentation UX patterns and developer experience optimization
• Deployment automation and CI/CD integration for documentation maintenance
• Sub-agent coordination for large-scale API analysis and documentation generation

IF $ARGUMENTS provided: IF $ARGUMENTS is file:

• SET scope to "single_file"
• ANALYZE specific route file for endpoint definitions
• EXTRACT authentication and middleware requirements

ELSE IF $ARGUMENTS is directory:

• SET scope to "directory_scan"
• RECURSIVELY process all controller/handler files
• BUILD comprehensive API specification with hierarchy

ELSE:

• SET scope to "project_wide"
• SCAN entire project for API route definitions and controllers
• DETECT existing OpenAPI/Swagger specifications
• ANALYZE framework structure for automatic documentation

STEP 3: Framework detection and analysis

TRY:

• EXECUTE systematic framework detection from Context section
• IDENTIFY primary backend framework(s) in use
• DETERMINE API pattern conventions for detected frameworks
• SAVE framework information to session state

**Framework Analysis Logic:**

CASE framework_indicators from Context: WHEN contains "express" OR "fastify":

• SET framework to "node_express"
• SEARCH for: `fd "(routes|controllers)" --type d`
• EXTRACT patterns: `rg "(app|router)\.(get|post|put|delete|patch)" --type js --type ts -A 5`

WHEN contains "axum" OR "actix":

• SET framework to "rust_web"
• SEARCH for: `fd "src" --type d`
• EXTRACT patterns: `rg "Router::new\(\)|\.route\(|#\[axum::" --type rust -A 3`

WHEN contains "spring" OR framework indicators show Java:

• SET framework to "java_spring"
• SEARCH for: `fd "(controller|resource)" --type d`
• EXTRACT patterns: `rg "@(RestController|Path|GET|POST|PUT|DELETE)Mapping" --type java -A 3`

WHEN contains "gin" OR "echo":

• SET framework to "go_web"
• EXTRACT patterns: `rg "router\.(GET|POST|PUT|DELETE)|func.*Handler" --type go -A 3`

WHEN API files > 20 AND multiple frameworks detected:

• USE sub-agent delegation for parallel framework analysis
• DELEGATE framework-specific documentation generation

CATCH (framework_detection_failed):

• LOG detection failures to session state
• CONTINUE with generic HTTP documentation approach
• PROVIDE manual framework specification option

STEP 4: Documentation generation strategy selection

BASED ON detected frameworks and project complexity:

FOR comprehensive projects (>50 endpoints OR multiple frameworks):

**Use parallel sub-agents for optimal performance:**

Analyze this API codebase using 5 parallel agents:
1. Schema Analysis Agent: Extract data models, types, and validation rules
2. Endpoint Discovery Agent: Map all API routes, methods, and parameter patterns
3. Authentication Analysis Agent: Document auth flows, middleware, and security patterns
4. Response Analysis Agent: Analyze response schemas, status codes, and error handling
5. Integration Documentation Agent: Create deployment guides, testing frameworks, and CI/CD integration

Each agent should focus exclusively on their domain and provide structured output for synthesis.

FOR targeted projects (<50 endpoints, single framework):

• EXECUTE sequential documentation generation
• FOCUS on framework-specific patterns and conventions
• GENERATE comprehensive OpenAPI specification

STEP 5: Execute documentation generation workflow

FOR EACH detected framework:

• GENERATE framework-specific OpenAPI specifications
• CREATE interactive documentation interfaces
• EXTRACT schema definitions from code
• COMPILE multi-language code examples
• VALIDATE generated documentation completeness

STEP 6: State management and checkpoint creation

• UPDATE session state with generation progress
• CREATE checkpoint: `/tmp/api-docs-checkpoint-$SESSION_ID.json`
• SAVE generated specifications for review
• PREPARE deployment-