ennam-django-apidog 0.1.0

Django integration for APIDOG - Export, sync, and manage OpenAPI schemas

ennam-django-apidog

Django integration for APIDOG - Export, sync, and manage OpenAPI schemas between Django REST Framework and APIDOG Cloud.

Features

• Export OpenAPI Schema - Generate OpenAPI 3.0 schemas from your Django REST Framework APIs
• Sync with APIDOG Cloud - Push and pull schemas to/from APIDOG Cloud
• Compare Schemas - Compare local schemas with cloud versions
• Environment Management - Generate environment configurations for different deployments
• Schema Hooks - Custom drf-spectacular extensions for handling edge cases
• Templates - Ready-to-use Makefile, Docker Compose, and configuration files

Installation

pip install ennam-django-apidog

Quick Start

1. Add to INSTALLED_APPS

# settings.py
INSTALLED_APPS = [
    ...
    'rest_framework',
    'drf_spectacular',
    'ennam_django_apidog',
]

2. Configure DRF Spectacular

# settings.py
REST_FRAMEWORK = {
    'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
}

SPECTACULAR_SETTINGS = {
    'TITLE': 'Your API',
    'DESCRIPTION': 'Your API description',
    'VERSION': '1.0.0',
    'SERVE_INCLUDE_SCHEMA': False,
}

3. Add URL Routes

# urls.py
from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerView

urlpatterns = [
    ...
    path('api/schema/', SpectacularAPIView.as_view(), name='schema'),
    path('api/schema/swagger-ui/', SpectacularSwaggerView.as_view(url_name='schema'), name='swagger-ui'),
]

4. Initialize APIDOG

python manage.py apidog init

5. Export Schema

python manage.py apidog export

Configuration

Configure APIDOG settings in your Django settings.py:

APIDOG_SETTINGS = {
    # Output directory for schemas (default: apidog/ at project root)
    'OUTPUT_DIR': None,

    # Schema endpoint (default: /api/schema/)
    'SCHEMA_ENDPOINT': '/api/schema/',

    # APIDOG Cloud credentials
    'PROJECT_ID': 'your-project-id',  # or use env var APIDOG_PROJECT_ID
    'TOKEN': 'your-api-token',        # or use env var APIDOG_TOKEN

    # API configuration
    'API_VERSION': '2024-03-28',
    'API_BASE_URL': 'https://api.apidog.com/v1',
    'TIMEOUT': 60,

    # Environment configurations
    'ENVIRONMENTS': {
        'local': {
            'name': 'Local Development',
            'base_url': 'http://localhost:8000',
        },
        'production': {
            'name': 'Production',
            'base_url': 'https://api.yourapp.com',
        },
    },
}

Or use environment variables:

export APIDOG_PROJECT_ID="your-project-id"
export APIDOG_TOKEN="your-api-token"

Commands

Initialize Project

# Create apidog directory and templates
python manage.py apidog init

# Force overwrite existing files
python manage.py apidog init --force

Export Schema

# Export as JSON (default)
python manage.py apidog export

# Export as YAML
python manage.py apidog export --format yaml

# Custom output directory
python manage.py apidog export --output /path/to/output/

Validate Schema

# Validate latest schema
python manage.py apidog validate

# Validate specific file
python manage.py apidog validate --file /path/to/schema.json

Push to APIDOG Cloud

# Push latest schema
python manage.py apidog push

# Push specific file
python manage.py apidog push --file /path/to/schema.json

Pull from APIDOG Cloud

# Pull to default location
python manage.py apidog pull

# Pull to specific file
python manage.py apidog pull --output /path/to/output.json

Compare Schemas

# Compare local with cloud
python manage.py apidog compare

Generate Environment Config

python manage.py apidog env-config

Using Schema Hooks

Add custom schema hooks to handle edge cases:

# settings.py
SPECTACULAR_SETTINGS = {
    ...
    'PREPROCESSING_HOOKS': [
        'ennam_django_apidog.schema_hooks.preprocess_exclude_problematic_views',
    ],
    'EXTENSIONS': [
        'ennam_django_apidog.schema_hooks.BaseSerializerExtension',
    ],
}

Makefile Commands

After running apidog init, use the Makefile for shortcuts:

# Show help
make -f Makefile.apidog help

# Export schema
make -f Makefile.apidog export

# Push to cloud
make -f Makefile.apidog push

# Compare with cloud
make -f Makefile.apidog compare

# Export and push
make -f Makefile.apidog sync

Docker Support

Use the generated Docker Compose file for mock server:

# Start mock server
docker-compose -f docker-compose.apidog.yml up -d apidog-mock

# Mock server available at http://localhost:4010

CI/CD Integration

Example GitHub Actions workflow:

- name: Export OpenAPI Schema
  run: |
    python manage.py apidog export --format json

- name: Push to APIDOG
  env:
    APIDOG_PROJECT_ID: ${{ secrets.APIDOG_PROJECT_ID }}
    APIDOG_TOKEN: ${{ secrets.APIDOG_TOKEN }}
  run: |
    python manage.py apidog push

Documentation

For full documentation, see docs/GUIDE.md.

Requirements

• Python >= 3.8
• Django >= 3.2
• Django REST Framework >= 3.12
• drf-spectacular >= 0.26

License

MIT License - see LICENSE for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Links

• APIDOG Website
• drf-spectacular Documentation
• Django REST Framework