API Documentation Generator

Generates comprehensive markdown API documentation by scanning FastAPI routes, Pydantic models, DRF viewsets, and serializers. Also detects drift between existing documentation and current code.

When to Use

• You need to generate API documentation from a FastAPI or Django REST Framework project
• You want to check if existing API docs are still accurate after code changes
• You need to document request/response schemas from Pydantic models or DRF serializers
• You want a quick overview of all endpoints in your project

Prerequisites

• A FastAPI or Django REST Framework project
• Route/view definitions accessible in the codebase

Workflow

/api-docs generate — Generate API documentation

1. Detect API framework:

   # FastAPI detection
   grep -r "APIRouter\|FastAPI()" --include="*.py" .
   
   # Django REST Framework detection
   grep -r "ViewSet\|APIView\|@api_view" --include="*.py" .
   

2. For FastAPI projects:

   • Find all router files and route definitions
   • Extract: HTTP method, path, request/response Pydantic models, docstrings, dependencies
   • Parse Pydantic models for field types, descriptions, defaults, validation:

     grep -r "class.*BaseModel" --include="*.py" -l .
     

3. For DRF projects:

   • Find all viewsets, views, and URL configurations
   • Extract: actions (list, create, retrieve, update, destroy, custom), serializers, permissions
   • Parse serializers for field types, required/optional, validation:

     grep -r "class.*Serializer" --include="*.py" -l .
     

4. Generate markdown documentation:

   # API Documentation
   
   ## Authentication
   {Detected auth mechanism}
   
   ## Endpoints
   
   ### {Group/Router Name}
   
   #### `{METHOD} {path}`
   {Description from docstring}
   
   **Request Body:**
   | Field | Type | Required | Description |
   |-------|------|----------|-------------|
   
   **Response:**
   | Field | Type | Description |
   |-------|------|-------------|
   
   **Status Codes:**
   | Code | Description |
   |------|-------------|
   

5. Write to docs/api.md or user-specified location.

6. Offer to add a table of contents with links to each endpoint group.

/api-docs diff — Detect documentation drift

1. Read existing API documentation file (docs/api.md or user-specified location).
2. Scan current code for all endpoints (same detection as generate).
3. Compare documented endpoints vs actual endpoints:
   • New endpoints not in docs
   • Removed endpoints still in docs
   • Changed request/response schemas
   • Changed paths or methods
4. Present a drift report with specific discrepancies:

   API Documentation Drift Report
   ==============================
   
   Added (not documented):
   - POST /api/v1/users/bulk-invite
   
   Removed (still documented):
   - DELETE /api/v1/users/{id}/avatar
   
   Changed:
   - PUT /api/v1/users/{id}
     - Added field: `phone_number` (string, optional)
     - Removed field: `legacy_id`
   

5. Offer to update the documentation with the detected changes.

Troubleshooting