api-documentation

API Documentation

When to Use

• Building or updating REST/GraphQL API documentation
• Onboarding new developers who need to understand available endpoints
• Preparing API reference docs for external consumers
• Ensuring API docs stay synchronized with implementation
• Creating OpenAPI/Swagger specifications from existing code

Prerequisites

• API source code with route definitions
• Understanding of the API framework (Express, FastAPI, Gin, etc.)
• Knowledge of request/response formats and authentication requirements

Workflow

1. Discover All Endpoints

# Express / Node.js
grep -rn "router\.\(get\|post\|put\|delete\|patch\)\|app\.\(get\|post\|put\|delete\|patch\)" src/ --include="*.ts" --include="*.js"

# FastAPI / Python
grep -rn "@app\.\(get\|post\|put\|delete\)\|@router\." src/ --include="*.py"

# Go / Gin
grep -rn "\.GET\|\.POST\|\.PUT\|\.DELETE" . --include="*.go"

Use explore agent for a comprehensive map:

task agent_type: "explore"
prompt: "Map all API endpoints in this project. For each endpoint list: HTTP method, path, handler function name, file location, and any middleware applied."

2. Document Each Endpoint

For each endpoint, capture:

## POST /api/users

Create a new user account.

**Authentication:** Bearer token required

**Request Body:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| email | string | Yes | Valid email address |
| name | string | Yes | Display name (1-100 chars) |
| role | string | No | User role (default: "viewer") |

**Response 201:**
```json
{
  "id": "usr_abc123",
  "email": "[email protected]",
  "name": "Jane Doe",
  "role": "viewer",
  "createdAt": "2024-01-15T10:30:00Z"
}

Error Responses:

Status	Description
400	Invalid request body
409	Email already exists
401	Missing or invalid auth token

### 3. Extract Types and Schemas
```powershell
# Find request/response type definitions
grep -rn "interface.*Request\|interface.*Response\|type.*Payload" src/ --include="*.ts" -A 10

# Find validation schemas (Zod, Joi, etc.)
grep -rn "z\.object\|Joi\.object\|Schema" src/ --include="*.ts" -A 10