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": "user@example.com",
  "name": "Jane Doe",
  "role": "viewer",
  "createdAt": "2024-01-15T10:30:00Z"
}

Error Responses:

### 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

4. Document Authentication

# Find auth middleware and configuration
grep -rn "auth\|jwt\|bearer\|apiKey\|passport" src/middleware/ --include="*.ts" -A 5

## Authentication

All endpoints except `POST /auth/login` require a Bearer token.

```bash
curl -H "Authorization: Bearer <token>" https://api.example.com/users

Obtaining a Token

curl -X POST https://api.example.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "secret"}'

### 5. Add Working Examples
```powershell
# Test each documented example against a running server
# Start the dev server
npm run dev  # mode: async, detach: true

# Verify an endpoint
curl -s http://localhost:3000/api/health | python -m json.tool

6. Generate OpenAPI Spec (Optional)

# If using a framework that supports auto-generation
npx swagger-jsdoc -d src/swagger-config.js -o docs/openapi.json

# Or generate from TypeScript types
npx ts-to-openapi --input src/types/ --output docs/openapi.yaml

Examples

Documenting a CRUD API

# 1. Find all route files
glob pattern="src/routes/**/*.ts"

# 2. For each route file, extract endpoints and their handlers
grep -rn "router\." src/routes/users.ts -A 3

# 3. Find the handler implementation for request/response details
grep -rn "export.*function\|export.*const.*=" src/controllers/users.ts -A 15

Quick API Reference Table

| Method | Path | Description | Auth |
|--------|------|-------------|------|
| GET | /api/users | List all users | Yes |
| POST | /api/users | Create user | Yes |
| GET | /api/users/:id | Get user by ID | Yes |
| PUT | /api/users/:id | Update user | Yes |
| DELETE | /api/users/:id | Delete user | Admin |

Tips

• Generate from code when possible — manually written docs drift from reality
• Include curl examples for every endpoint — they're the most portable format
• Document error responses, not just success cases
• Add rate limiting and pagination details if applicable
• Version your API docs alongside API code (same branch, same PR)
• Use task agent to verify documented curl commands actually work against the API
• Include a Postman collection or similar importable format for API consumers