docs/
├── api/
│   ├── index.md              # API overview
│   ├── authentication.md     # Auth guide
│   ├── errors.md             # Error reference
│   ├── rate-limiting.md      # Rate limit info
│   └── endpoints/
│       ├── users.md
│       ├── products.md
│       └── orders.md
├── guides/
│   ├── getting-started.md
│   ├── pagination.md
│   └── webhooks.md
└── sdks/
    ├── javascript.md
    ├── python.md
    └── curl.md

// scripts/generate-api-docs.ts
import * as fs from "fs";
import * as path from "path";

interface RouteInfo {
  method: string;
  path: string;
  name: string;
  description?: string;
  params?: ParamInfo[];
  queryParams?: ParamInfo[];
  requestBody?: SchemaInfo;
  responses?: ResponseInfo[];
  auth?: boolean;
  tags?: string[];
}

interface ParamInfo {
  name: string;
  type: string;
  required: boolean;
  description?: string;
  example?: string;
}

interface SchemaInfo {
  type: string;
  properties?: Record<string, PropertyInfo>;
  required?: string[];
  example?: object;
}

interface PropertyInfo {
  type: string;
  description?: string;
  example?: unknown;
  enum?: string[];
  format?: string;
}

interface ResponseInfo {
  status: number;
  description: string;
  schema?: SchemaInfo;
  example?: object;
}

interface DocsOptions {
  title: string;
  baseUrl: string;
  version: string;
  outputDir: string;
  format: "markdown" | "html" | "docusaurus";
}

function generateApiDocs(routes: RouteInfo[], options: DocsOptions): void {
  const { outputDir } = options;

  // Create directories
  fs.mkdirSync(path.join(outputDir, "api", "endpoints"), { recursive: true });
  fs.mkdirSync(path.join(outputDir, "guides"), { recursive: true });

  // Generate overview
  generateOverview(options);

  // Generate auth docs
  generateAuthDocs(options);

  // Generate error docs
  generateErrorDocs(options);

  // Group routes by resource
  const groupedRoutes = groupRoutesByResource(routes);

  // Generate endpoint docs
  for (const [resource, resourceRoutes] of Object.entries(groupedRoutes)) {
    const content = generateEndpointDoc(resource, resourceRoutes, options);
    const filePath = path.join(outputDir, "api", "endpoints", `${resource}.md`);
    fs.writeFileSync(filePath, content);
  }

  // Generate getting started guide
  generateGettingStarted(routes, options);
}

function generateEndpointDoc(
  resource: string,
  routes: RouteInfo[],
  options: DocsOptions
): string {
  const lines: string[] = [];

  // Header
  lines.push(`# ${capitalize(resource)}`);
  lines.push("");
  lines.push(`Endpoints for managing ${resource}.`);
  lines.push("");

  // Table of contents
  lines.push("## Endpoints");
  lines.push("");
  lines.push("| Method | Endpoint | Description |");
  lines.push("|--------|----------|-------------|");

  for (const route of routes) {
    lines.push(
      `| \`${route.method}\` | \`${route.path}\` | ${route.description || route.name} |`
    );
  }
  lines.push("");

  // Detailed documentation for each endpoint
  for (const route of routes) {
    lines.push(generateEndpointSection(route, options));
    lines.push("");
  }

  return lines.join("\n");
}

function generateEndpointSection(
  route: RouteInfo,
  options: DocsOptions
): string {
  const lines: string[] = [];
  const anchor = route.name.toLowerCase().replace(/\s+/g, "-");

  // Endpoint header
  lines.push(`## ${route.name} {#${anchor}}`);
  lines.push("");
  lines.push(
    `<span class="method method-${route.method.toLowerCase()}">${route.method}</span> \`${route.path}\``
  );
  lines.push("");

  if (route.description) {
    lines.push(route.description);
    lines.push("");
  }

  // Authentication
  if (route.auth) {
    lines.push("### Authentication");
    lines.push("");
    lines.push("This endpoint requires authentication. Include the Bearer token in the Authorization header.");
    lines.push("");
  }

  // Path parameters
  if (route.params?.length) {
    lines.push("### Path Parameters");
    lines.push("");
    lines.push("| Parameter | Type | Required | Description |");
    lines.push("|-----------|------|----------|-------------|");

    for (const param of route.params) {
      lines.push(
        `| \`${param.name}\` | ${param.type} | ${param.required ? "Yes" : "No"} | ${param.description || "-"} |`
      );
    }
    lines.push("");
  }

  // Query parameters
  if (route.queryParams?.length) {
    lines.push("### Query Parameters");
    lines.push("");
    lines.push("| Parameter | Type | Required | Default | Description |");
    lines.push("|-----------|------|----------|---------|-------------|");

    for (const param of route.queryParams) {
      lines.push(
        `| \`${param.name}\` | ${param.type} | ${param.required ? "Yes" : "No"} | ${param.example || "-"} | ${param.description || "-"} |`
      );
    }
    lines.push("");
  }

  // Request body
  if (route.requestBody) {
    lines.push("### Request Body");
    lines.push("");
    lines.push("```json");
    lines.push(JSON.stringify(route.requestBody.example || {}, null, 2));
    lines.push("```");
    lines.push("");

    if (route.requestBody.properties) {
      lines.push("| Field | Type | Required | Description |");
      lines.push("|-------|------|----------|-------------|");

      for (const [name, prop] of Object.entries(route.requestBody.properties)) {
        const required = route.requestBody.required?.includes(name)
          ? "Yes"
          : "No";
        lines.push(
          `| \`${name}\` | ${prop.type} | ${required} | ${prop.description || "-"} |`
        );
      }
      lines.push("");
    }
  }

  // Responses
  lines.push("### Responses");
  lines.push("");

  const responses = route.responses || [
    { status: 200, description: "Successful response" },
    { status: 400, description: "Bad request" },
    { status: 401, description: "Unauthorized" },
    { status: 404, description: "Not found" },
  ];

  for (const response of responses) {
    lines.push(`#### ${response.status} ${response.description}`);
    lines.push("");

    if (response.example) {
      lines.push("```json");
      lines.push(JSON.stringify(response.example, null, 2));
      lines.push("```");
      lines.push("");
    }
  }

  // Example request
  lines.push("### Example Request");
  lines.push("");
  lines.push("```bash");
  lines.push(generateCurlExample(route, options));
  lines.push("```");
  lines.push("");

  return lines.join("\n");
}

function generateCurlExample(route: RouteInfo, options: DocsOptions): string {
  const parts: string[] = ["curl"];
  parts.push(`-X ${route.method}`);

  let url = `${options.baseUrl}${route.path}`;
  url = url.replace(/:(\w+)/g, "{$1}");
  parts.push(`"${url}"`);

  if (["POST", "PUT", "PATCH"].includes(route.method)) {
    parts.push('-H "Content-Type: application/json"');
  }

  if (route.auth) {
    parts.push('-H "Authorization: Bearer YOUR_TOKEN"');
  }

  if (route.requestBody?.example) {
    parts.push(`-d '${JSON.stringify(route.requestBody.example)}'`);
  }

  return parts.join(" \\\n  ");
}

function generateOverview(options: DocsOptions): void {
  const content = `# ${options.title} API Reference

Version: ${options.version}

Base URL: \`${options.baseUrl}\`

if (!groups[resource]) {
  groups[resource] = [];
}
groups[resource].push(route);

undefined

undefined

{
  "success": true,
  "data": [
    {
      "id": "user_abc123",
      "name": "John Doe",
      "email": "john@example.com",
      "role": "user",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 156,
    "total_pages": 16
  }
}

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}

curl -X GET "https://api.example.com/users?page=1&limit=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "name": "John Doe",
  "email": "john@example.com",
  "role": "user"
}

{
  "success": true,
  "data": {
    "id": "user_xyz789",
    "name": "John Doe",
    "email": "john@example.com",
    "role": "user",
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request data",
    "details": {
      "email": ["Invalid email format"]
    }
  }
}

curl -X POST "https://api.example.com/users" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"name": "John Doe", "email": "john@example.com"}'

undefined

#!/usr/bin/env node
// scripts/docs-gen.ts
import * as fs from "fs";
import { program } from "commander";

program
  .name("docs-gen")
  .description("Generate API documentation from routes")
  .option("-f, --framework <type>", "Framework (express|nextjs|fastify)", "express")
  .option("-s, --source <path>", "Source directory", "./src")
  .option("-o, --output <path>", "Output directory", "./docs")
  .option("-t, --title <name>", "API title", "My API")
  .option("-v, --version <version>", "API version", "1.0.0")
  .option("-b, --base-url <url>", "Base URL", "https://api.example.com")
  .option("--format <type>", "Output format (markdown|html|docusaurus)", "markdown")
  .parse();

const options = program.opts();

async function main() {
  const routes = await scanRoutes(options.framework, options.source);

  generateApiDocs(routes, {
    title: options.title,
    baseUrl: options.baseUrl,
    version: options.version,
    outputDir: options.output,
    format: options.format,
  });

  console.log(`Generated documentation in ${options.output}`);
}

main();