# 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