first commit
This commit is contained in:
Holger Sielaff
262
README.md
Normal file
262
README.md
Normal file
@@ -0,0 +1,262 @@
|
||||
# Django Enhanced API Docs
|
||||
|
||||
Enhanced API documentation for Django REST Framework using drf-spectacular with custom schema generation, automatic parameter descriptions, and code samples.
|
||||
|
||||
## Features
|
||||
|
||||
- **Optional API Documentation**: Enable/disable API docs via environment variable
|
||||
- **Enhanced Schema Generation**: Automatic parameter descriptions for filters, search, ordering, and pagination
|
||||
- **Language Support**: Built-in support for translatable fields with language parameter
|
||||
- **Code Samples**: Automatic cURL code sample generation for all endpoints
|
||||
- **Custom Tags**: Organize endpoints with custom tags mapped to ViewSet classes
|
||||
- **Comprehensive Error Responses**: Automatic addition of standard HTTP error responses
|
||||
- **Pagination Examples**: Dynamic pagination URL examples based on actual endpoints
|
||||
|
||||
## Installation
|
||||
|
||||
### Via pip (when published)
|
||||
|
||||
```bash
|
||||
pip install django-enhanced-apidocs
|
||||
```
|
||||
|
||||
### Via Git (development)
|
||||
|
||||
```bash
|
||||
pip install git+https://github.com/yourusername/django-enhanced-apidocs.git
|
||||
```
|
||||
|
||||
### As Git Submodule (development)
|
||||
|
||||
```bash
|
||||
cd your-django-project
|
||||
git submodule add https://github.com/yourusername/django-enhanced-apidocs.git
|
||||
pip install -e ./django-enhanced-apidocs
|
||||
```
|
||||
|
||||
### Editable Installation (local development)
|
||||
|
||||
```bash
|
||||
pip install -e /path/to/django-enhanced-apidocs
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### 1. Add to INSTALLED_APPS
|
||||
|
||||
Add the following to your Django `settings.py`:
|
||||
|
||||
```python
|
||||
# Enable API documentation (default: enabled in DEBUG mode)
|
||||
ENABLE_API_DOCS = os.environ.get('ENABLE_API_DOCS', str(DEBUG)).lower() in ('true', '1', 'yes')
|
||||
|
||||
INSTALLED_APPS = [
|
||||
# ... your other apps
|
||||
]
|
||||
|
||||
# Conditionally add API documentation
|
||||
if ENABLE_API_DOCS:
|
||||
INSTALLED_APPS.extend(['drf_spectacular', 'django_enhanced_apidocs'])
|
||||
```
|
||||
|
||||
### 2. Configure REST Framework
|
||||
|
||||
```python
|
||||
REST_FRAMEWORK = {
|
||||
'DEFAULT_AUTHENTICATION_CLASSES': [
|
||||
'rest_framework.authentication.BasicAuthentication',
|
||||
'rest_framework.authentication.SessionAuthentication',
|
||||
],
|
||||
'DEFAULT_PERMISSION_CLASSES': [
|
||||
'rest_framework.permissions.IsAuthenticated',
|
||||
],
|
||||
'DEFAULT_PAGINATION_CLASS': 'rest_framework.pagination.PageNumberPagination',
|
||||
'PAGE_SIZE': 20,
|
||||
}
|
||||
|
||||
# Set schema class when API docs are enabled
|
||||
if ENABLE_API_DOCS:
|
||||
REST_FRAMEWORK['DEFAULT_SCHEMA_CLASS'] = 'django_enhanced_apidocs.schema.CustomAutoSchema'
|
||||
```
|
||||
|
||||
### 3. Import Spectacular Settings
|
||||
|
||||
```python
|
||||
# In settings.py
|
||||
if ENABLE_API_DOCS:
|
||||
from django_enhanced_apidocs.conf import get_spectacular_settings
|
||||
|
||||
# Pass your dotenv config dict
|
||||
SPECTACULAR_SETTINGS = get_spectacular_settings(config)
|
||||
```
|
||||
|
||||
The `config` parameter should be a dictionary with at least:
|
||||
- `LOCAL_SWAGGER_HOST` (optional): Server URL for API documentation (default: 'http://localhost:8000')
|
||||
|
||||
You can also override settings after import:
|
||||
|
||||
```python
|
||||
if ENABLE_API_DOCS:
|
||||
from django_enhanced_apidocs.conf import get_spectacular_settings
|
||||
|
||||
SPECTACULAR_SETTINGS = get_spectacular_settings(config)
|
||||
|
||||
# Customize settings
|
||||
SPECTACULAR_SETTINGS['TITLE'] = 'My API'
|
||||
SPECTACULAR_SETTINGS['DESCRIPTION'] = 'My API Description'
|
||||
SPECTACULAR_SETTINGS['VERSION'] = '2.0.0'
|
||||
SPECTACULAR_SETTINGS['CONTACT'] = {'email': 'api@example.com'}
|
||||
```
|
||||
|
||||
### 4. Include URLs
|
||||
|
||||
Add documentation URLs to your `urls.py`:
|
||||
|
||||
```python
|
||||
from django.urls import path, include
|
||||
from django.conf import settings
|
||||
|
||||
urlpatterns = [
|
||||
# Your API endpoints
|
||||
path('api/v1/', include('your_app.urls')),
|
||||
]
|
||||
|
||||
# Conditionally include API documentation URLs
|
||||
if getattr(settings, 'ENABLE_API_DOCS', False):
|
||||
urlpatterns.append(path('', include('django_enhanced_apidocs.urls')))
|
||||
```
|
||||
|
||||
This adds the following endpoints:
|
||||
- `/swagger/` - Swagger UI
|
||||
- `/redoc/` - ReDoc UI
|
||||
- `/api/schema/` - OpenAPI JSON schema
|
||||
|
||||
## Environment Variables
|
||||
|
||||
Control API documentation via environment variables:
|
||||
|
||||
```bash
|
||||
# Enable API docs (default: true in DEBUG mode)
|
||||
ENABLE_API_DOCS=true
|
||||
|
||||
# Set custom server URL for API docs
|
||||
LOCAL_SWAGGER_HOST=http://localhost:8000
|
||||
```
|
||||
|
||||
Or in your `.env` file:
|
||||
|
||||
```
|
||||
ENABLE_API_DOCS=false # Disable in production
|
||||
LOCAL_SWAGGER_HOST=https://api.example.com
|
||||
```
|
||||
|
||||
## Custom Tags Configuration
|
||||
|
||||
The package comes with pre-configured tags for common Django apps. You can customize them in your settings:
|
||||
|
||||
```python
|
||||
if ENABLE_API_DOCS:
|
||||
from django_enhanced_apidocs.conf import get_spectacular_settings
|
||||
|
||||
SPECTACULAR_SETTINGS = get_spectacular_settings(config)
|
||||
|
||||
# Add custom tags
|
||||
SPECTACULAR_SETTINGS['TAGS'] = [
|
||||
{
|
||||
'name': 'Products',
|
||||
'description': 'Product management endpoints',
|
||||
'viewsets': ['ProductViewSet', 'ProductVersionViewSet']
|
||||
},
|
||||
{
|
||||
'name': 'Users',
|
||||
'description': 'User management endpoints',
|
||||
'viewsets': ['UserViewSet']
|
||||
},
|
||||
]
|
||||
```
|
||||
|
||||
## Features in Detail
|
||||
|
||||
### Automatic Parameter Descriptions
|
||||
|
||||
The package automatically enhances query parameters with human-readable descriptions:
|
||||
|
||||
- **Search**: Describes which fields are searched
|
||||
- **Ordering**: Explains ascending/descending syntax
|
||||
- **Pagination**: Documents page number format
|
||||
- **Filters**: Generates descriptions based on field types (boolean, integer, foreign key, etc.)
|
||||
|
||||
### Language Parameter
|
||||
|
||||
For projects using translatable fields (e.g., `django-translatable-fields`), the package automatically adds a `lang` parameter to GET endpoints:
|
||||
|
||||
```
|
||||
?lang=en # Returns English translations
|
||||
?lang=de # Returns German translations
|
||||
?lang=fr # Returns French translations
|
||||
```
|
||||
|
||||
### Automatic cURL Code Samples
|
||||
|
||||
Every endpoint includes a ready-to-use cURL command with:
|
||||
- Correct HTTP method
|
||||
- Authentication headers
|
||||
- Request body (for POST/PUT/PATCH)
|
||||
- Sample data based on serializer schema
|
||||
|
||||
### Standard Error Responses
|
||||
|
||||
All endpoints automatically document standard HTTP error responses:
|
||||
- 400 Bad Request
|
||||
- 401 Unauthorized
|
||||
- 403 Forbidden
|
||||
- 404 Not Found
|
||||
- 409 Conflict
|
||||
- 500 Internal Server Error
|
||||
|
||||
## Usage Example
|
||||
|
||||
After installation, access your API documentation at:
|
||||
|
||||
- **Swagger UI**: http://localhost:8000/swagger/
|
||||
- **ReDoc**: http://localhost:8000/redoc/
|
||||
- **OpenAPI Schema**: http://localhost:8000/api/schema/
|
||||
|
||||
## Disabling in Production
|
||||
|
||||
To disable API documentation in production:
|
||||
|
||||
```bash
|
||||
# In your production .env file
|
||||
ENABLE_API_DOCS=false
|
||||
```
|
||||
|
||||
Or in your settings:
|
||||
|
||||
```python
|
||||
ENABLE_API_DOCS = False
|
||||
```
|
||||
|
||||
When disabled:
|
||||
- `/swagger/`, `/redoc/`, `/api/schema/` return 404
|
||||
- `drf_spectacular` and `django_enhanced_apidocs` are not loaded
|
||||
- No performance impact on API endpoints
|
||||
|
||||
## Requirements
|
||||
|
||||
- Python >= 3.9
|
||||
- Django >= 4.0
|
||||
- djangorestframework >= 3.14
|
||||
- drf-spectacular >= 0.26
|
||||
|
||||
## License
|
||||
|
||||
MIT License - see LICENSE file for details
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions are welcome! Please feel free to submit a Pull Request.
|
||||
|
||||
## Credits
|
||||
|
||||
Created by KBS GmbH
|
||||
Reference in New Issue
Block a user