api_docs

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

Problem	Cause	Solution
Framework not detected	No FastAPI or DRF imports found	Verify the project uses a supported framework; check for non-standard import patterns
Routes spread across many files	Large project with modular routing	The tool scans recursively; ensure all route files use standard decorators and patterns
Dynamic route generation	Routes created programmatically at runtime	Document dynamic routes manually or point the tool to the route registration code
Pydantic v1 vs v2 differences	Model syntax varies between versions	The tool handles both BaseModel styles; flag any issues for manual review
Existing docs in non-standard format	Docs don't follow expected markdown structure	Use generate to create fresh docs, then manually merge custom sections