drf-api-doc-generator
Advanced tools
Auto-generate production-quality API & WebSocket documentation (PDF, HTML, JSON/OpenAPI) for Django REST Framework with a single command
Auto-generate production-quality API & WebSocket documentation for Django REST Framework with a single command! 🚀
Stop manually writing API documentation! This tool automatically discovers your DRF endpoints, serializers, authentication, permissions, and WebSocket consumers, then generates beautiful documentation in PDF, HTML, or OpenAPI JSON format.
pip install drf-api-doc-generator
Generate complete documentation for all apps and WebSockets, zipped and ready to share:
python manage.py generate_api_docs complete-project-zip-html
This single command will:
consumers.py (WebSocket) files# settings.py
INSTALLED_APPS = [
# ... your other apps
'rest_framework',
'api_docs_generator', # Add this line
]
# Generate PDF for a specific app
python manage.py generate_api_docs auth
# Generate for multiple apps
python manage.py generate_api_docs auth users products
# Generate all formats (PDF + HTML + JSON)
python manage.py generate_api_docs auth --format all
# Generate for all apps
python manage.py generate_api_docs --all
# Document a WebSocket consumer file
python manage.py generate_api_docs --websocket chat/consumers/dm_consumer.py
# Document multiple WebSocket files
python manage.py generate_api_docs --websocket chat/consumers/*.py
# Combine REST API and WebSocket documentation
python manage.py generate_api_docs auth --websocket chat/consumers/dm_consumer.py --format all
Documentation will be generated in ./api_docs/ directory:
api_docs_YYYYMMDD_HHMMSS.pdfapi_docs_YYYYMMDD_HHMMSS.htmlapi_docs_YYYYMMDD_HHMMSS.jsonpython manage.py generate_api_docs [OPTIONS] [APPS...]
| Option | Short | Description |
|---|---|---|
--all | Generate docs for all installed apps | |
--websocket | -ws | Path(s) to WebSocket consumer files |
--format | -f | Output format: pdf, html, json, or all (default: pdf) |
--output | -o | Output directory (default: ./api_docs/) |
--title | Custom documentation title | |
--api-version | API version string | |
--description | API description | |
--ws-base-url | WebSocket base URL (default: ws://domain) | |
--open | Open file after generation | |
-v 2 | Verbose output (show all endpoints) |
# Generate PDF with custom title
python manage.py generate_api_docs auth --title "My Awesome API"
# Generate with WebSocket and custom base URL
python manage.py generate_api_docs --websocket chat/consumers.py --ws-base-url wss://api.myapp.com
# Generate to custom directory
python manage.py generate_api_docs auth --output ./docs/api/
# Generate and open automatically
python manage.py generate_api_docs auth --format html --open
# Verbose mode - show all discovered endpoints
python manage.py generate_api_docs auth -v 2
The generated documentation for WebSocket consumers includes:
Client Action:
const ws = new WebSocket('ws://domain/ws/dm/123/?token=YOUR_JWT_TOKEN');
Server Response (on success):
{
"type": "connection_established",
"user_id": 123,
"timestamp": "2025-01-15T10:30:00.000Z"
}
Each action includes:
Events broadcast from server to clients:
Add optional configuration to your Django settings:
# settings.py
API_DOCS_CONFIG = {
'TITLE': 'My API Documentation',
'VERSION': '2.0.0',
'DESCRIPTION': 'Complete API reference for developers',
'CONTACT_EMAIL': 'api@example.com',
'LOGO_PATH': 'path/to/logo.png', # Optional logo for PDF cover
'THEME_COLOR': '#2563eb', # Primary theme color
'WS_BASE_URL': 'wss://api.example.com', # WebSocket base URL
}
class DMConsumer(AsyncJsonWebsocketConsumer):
"""
DM Consumer
Features:
- Lazy conversation creation (only on first message)
- Anyone can message anyone (unknown users allowed)
- Spam protection for unknown users
- Typing & recording indicators
- Read receipts
"""
pass
async def handle_send_message(self, content):
"""
Send message
Client sends:
{
"action": "send_message",
"content": "message text",
"msg_type": "text"
}
"""
pass
Name your handlers with handle_ prefix:
handle_send_messagehandle_typing_starthandle_mark_readProfessional documentation with:
Interactive documentation with:
Standard specification compatible with:
Contributions are welcome! Please feel free to submit a Pull Request.
git checkout -b feature/amazing-feature)git commit -m 'Add amazing feature')git push origin feature/amazing-feature)This project is licensed under the MIT License - see the LICENSE file for details.
Made with ❤️ for Django developers
FAQs
Auto-generate production-quality API & WebSocket documentation (PDF, HTML, JSON/OpenAPI) for Django REST Framework with a single command
We found that drf-api-doc-generator demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
The remediated findings include organization permission bugs, stale project access after transfers, OIDC replay edge cases, audit logging gaps, and an IDOR in API token deletion.
Research
/Security News
GitHub account BufferZoneCorp published sleeper packages that later added credential theft, GitHub Actions tampering, fake go wrappers, and SSH persistence.
Research
/Security News
Socket found a malicious Intercom PHP package on Packagist using Composer plugin execution to steal credentials and spread across ecosystems.