django-api-explorer 1.0.3

A powerful command-line tool and web interface for discovering, documenting, and testing API endpoints in Django projects

🚀 Django API Explorer

A powerful command-line tool and web interface for discovering, documenting, and testing API endpoints in Django projects. Automatically extracts URL patterns, HTTP methods, and generates ready-to-use cURL commands with comprehensive dummy data.

Latest Update: v1.0.3 - Fixed import issues and improved package structure for better PyPI compatibility. Clean release after resolving version conflicts.

✨ Features

🔍 Smart API Discovery

• Automatic URL Pattern Detection: Parse Django URL patterns and DRF routers
• HTTP Method Detection: Support for GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS
• Django REST Framework Support: Handle ViewSets, APIViews, and action decorators
• App-Specific Scanning: Scan individual Django apps or entire projects
• URL Parameter Extraction: Detect path parameters ({id}, <pk>, (?P<name>...))

🎨 Modern Web Interface

• Interactive Dashboard: Responsive, gradient-based UI with real-time search
• Shutter System: Click any API row to see detailed cURL commands
• Smart Filtering: Filter by app, method, or search terms
• Copy Functionality: One-click copy with visual feedback
• Auto-reload: Real-time updates when Django files change

🔧 Developer Workflow

• File Watching: Monitor Django project files for changes
• Hot Reload: Automatic UI updates without manual refresh
• CLI Interface: Modern Click-based command-line tool
• Multiple Output Formats: Terminal, browser, JSON, HTML
• Custom Ports: Avoid conflicts with existing servers

📊 Comprehensive Data Generation

• Smart cURL Commands: Replace URL parameters with sample values
• Dummy Data: Context-aware payloads for all endpoint types
• Authentication Headers: Realistic JWT tokens and API keys
• Complete Coverage: Include all fields, even optional ones
• Shell Compatibility: Properly escaped for terminal use

📤 Postman Integration

• One-Click Export: Export filtered APIs to Postman collection
• Smart Organization: Group requests by Django app
• Environment Variables: Pre-configured base URL and auth tokens
• Parameter Handling: Convert URL parameters to Postman variables
• Sample Data: Include request bodies for POST/PUT/PATCH
• Filter-Based Export: Export only selected APIs

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/SketchG2001/api-explorer.git
cd api-explorer

# Install dependencies
pip install -r requirements.txt

# Or using pipenv
pipenv install

Basic Usage

# Scan all apps in current Django project
python cli.py --browser

# Scan specific app
python cli.py --app users --browser

# Use custom Django settings
python cli.py --settings myproject.settings.dev --browser

# Enable file watching for auto-reload
python cli.py --app users --browser --watch

# Use custom port to avoid conflicts
python cli.py --app users --browser --watch --port 8005

Advanced Usage

# Export as JSON
python cli.py --json -o apis.json

# Generate cURL commands for terminal
python cli.py --curl

# Specify custom host
python cli.py --host https://api.example.com --browser

# Scan from different project directory
python cli.py --project-root /path/to/django/project --browser

📖 Detailed Documentation

Command Line Options

Option	Short	Description	Default
--project-root	-p	Django project root path	Current directory
--settings	-s	Django settings module	Auto-detect
--app	-a	Scan specific Django app	All apps
--browser	-b	Open results in browser	Terminal output
--watch	-w	Watch for file changes	Disabled
--curl		Generate cURL commands	Plain URLs
--json	-j	Output in JSON format	Text format
--output	-o	Save output to file	Console output
--host		Override host URL	From ALLOWED_HOSTS
--port		Web server port	8001

Web Interface Features

Interactive Dashboard

• Real-time Search: Filter endpoints by path, method, or app name
• App Filtering: Dropdown to filter by Django app
• Statistics: View total endpoints, methods, and apps
• Responsive Design: Works on desktop and mobile devices

Shutter System

• Inline Details: Opens directly below the clicked API row
• Method Separation: cURL commands grouped by HTTP method
• Copy Buttons: One-click copy with visual feedback
• Smart Highlighting: Visual feedback for selected endpoints

cURL Generation

• Parameter Replacement: URL parameters replaced with sample values
• Comprehensive Headers: Authentication, Content-Type, User-Agent, etc.
• Dummy Data: Context-aware sample payloads for POST/PUT requests
• Shell Compatibility: Properly escaped for terminal use

Postman Export

• One-Click Export: Export button in the top-right corner
• Filter-Based Export: Only exports currently filtered endpoints
• Smart Collection Naming: Names based on active filters
• App Organization: Groups requests by Django app
• Environment Variables: Pre-configured base_url, auth_token, api_key
• Parameter Variables: URL parameters converted to Postman variables
• Sample Data: Includes request bodies for POST/PUT/PATCH methods
• Download Ready: Direct download as .json file

File Watching & Auto-Reload

The file watcher monitors your Django project for changes and automatically reloads the UI:

# Enable file watching
python cli.py --browser --watch

# Use custom port
python cli.py --browser --watch --port 8005

Monitored Files:

• *.py - Python files
• urls.py - URL configurations
• views.py - View files
• models.py - Model files
• serializers.py - DRF serializers
• settings.py - Settings files

Ignored Files:

• __pycache__/
• *.pyc
• .git/
• node_modules/
• .venv/, venv/, env/
• .pytest_cache/
• migrations/

Django Integration

Project Setup

The Django API Explorer integrates seamlessly with your Django project:

# Navigate to your Django project root
cd /path/to/your/django/project

# Run the explorer from your project directory
python /path/to/api-explorer/cli.py --browser

# Or install it as a package and run from anywhere
pip install django-api-explorer
django-api-explorer --browser

Settings Loading

The tool automatically detects and loads Django settings:

# Auto-detection order:
1. Current directory settings
2. Specified --settings module
3. Fallback to minimal settings

# Example with custom settings
python cli.py --settings myproject.settings.dev --browser

Host Detection

Extracts hosts from Django's ALLOWED_HOSTS setting:

# From settings.py
ALLOWED_HOSTS = ['localhost', '127.0.0.1', 'api.example.com']

# Tool will use: http://127.0.0.1:8000 (fallback)

App Discovery

Automatically discovers installed Django apps:

# From settings.py
INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'myapp',
    'api',
]

URL Pattern Integration

Works with all Django URL pattern types:

# urls.py - Main project URLs
from django.urls import path, include
from rest_framework.routers import DefaultRouter
from myapp.views import UserViewSet

router = DefaultRouter()
router.register(r'users', UserViewSet)

urlpatterns = [
    path('admin/', admin.site.urls),
    path('api/', include(router.urls)),
    path('api/', include('myapp.urls')),
]

# myapp/urls.py - App-specific URLs
from django.urls import path
from . import views

urlpatterns = [
    path('users/', views.UserListView.as_view(), name='user-list'),
    path('users/<int:pk>/', views.UserDetailView.as_view(), name='user-detail'),
]

Django REST Framework Integration

Fully supports DRF patterns and conventions:

# views.py
from rest_framework import viewsets, status
from rest_framework.decorators import action
from rest_framework.response import Response

class UserViewSet(viewsets.ModelViewSet):
    queryset = User.objects.all()
    serializer_class = UserSerializer
    
    @action(detail=True, methods=['post'])
    def activate(self, request, pk=None):
        user = self.get_object()
        user.is_active = True
        user.save()
        return Response({'status': 'activated'})

# The explorer will detect:
# - GET /api/users/ (list)
# - POST /api/users/ (create)
# - GET /api/users/{id}/ (retrieve)
# - PUT /api/users/{id}/ (update)
# - DELETE /api/users/{id}/ (destroy)
# - POST /api/users/{id}/activate/ (custom action)

cURL Command Generation

The tool generates comprehensive cURL commands with:

URL Parameter Replacement

# Original URL: /api/users/{id}/profile/{field}
# Generated: /api/users/1/profile/email

Authentication Headers

# JWT Token
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

# API Key
-H "X-API-Key: api_key_123456789abcdef"

# Client ID
-H "X-Client-ID: client_987654321fedcba"

Sample Data Generation

{
  "name": "Premium Gaming Campaign 2024",
  "description": "High-performance gaming campaign",
  "budget": 50000.00,
  "start_date": "2024-01-01",
  "end_date": "2024-12-31",
  "target_audience": {
    "age_range": "18-35",
    "interests": ["gaming", "technology"],
    "location": "Worldwide"
  }
}

🏗️ Project Structure

api-exporer/
├── cli.py                 # Main command-line interface
├── requirements.txt       # Python dependencies
├── README.md             # This documentation
├── pyproject.toml        # Project metadata
├── MANIFEST.in           # Package manifest
├── core/                 # Core functionality
│   ├── __init__.py
│   ├── url_extractor.py  # URL pattern extraction
│   ├── method_detector.py # HTTP method detection
│   ├── settings_loader.py # Django settings loading
│   ├── formatter.py      # Output formatting
│   └── models.py         # Data models
├── web/                  # Web interface
│   ├── __init__.py
│   ├── enhanced_server.py # Enhanced HTTP server
│   ├── file_watcher_server.py # File watching server
│   └── templates/
│       └── enhanced_index.html # Main UI template
├── utils/                # Utility functions
│   ├── __init__.py
│   └── path_utils.py     # Path utilities
└── tests/                # Test suite
    ├── __init__.py
    ├── test_basic.py     # Basic functionality tests
    └── test_url_extractor.py # URL extraction tests

🔧 Development

Setup Development Environment

# Clone and setup
git clone < https://github.com/SketchG2001/api-explorer.git>
cd api-exporer

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Install development dependencies
pip install pytest black

Running Tests

# Run all tests
pytest

# Run specific test file
pytest tests/test_basic.py

# Run with coverage
pytest --cov=core --cov=web

Code Quality

# Format code
black .

# Lint code
# flake8 .  # Removed due to complexity issues

# Type checking (if using mypy)
mypy .

🐛 Troubleshooting

Common Issues

Port Already in Use

# Error: OSError: [Errno 48] Address already in use
# Solution: Use different port
python cli.py --browser --port 8005

Django Settings Not Found

# Error: Error loading Django settings
# Solution: Specify settings module
python cli.py --settings myproject.settings.dev --browser

Module Import Errors

# Error: No module named 'some_module'
# Solution: Activate Django project's virtual environment
cd /path/to/django/project
pipenv run python /path/to/api-exporer/cli.py --browser

JavaScript Errors in Browser

# Check browser console for errors
# Common fix: Clear browser cache and reload

Debug Mode

Enable debug output for troubleshooting:

# Set debug environment variable
export DEBUG=1
python cli.py --browser

# Or modify cli.py to add debug logging

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Code Style: Follow PEP 8 and use Black for formatting
• Testing: Add tests for new features
• Documentation: Update README.md for new features
• Type Hints: Use type hints for function parameters and return values

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License

MIT License

Copyright (c) 2024 Django API Explorer

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

🙏 Acknowledgments

• Django: For the amazing web framework
• Django REST Framework: For API development tools
• Click: For the command-line interface
• Rich: For beautiful terminal output
• Watchdog: For file system monitoring

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [e-mail]

---

Made with ❤️ for the Django community