Integrate OpenAPI/Swagger documentation using drf-spectacular, enhancing API documentation with comprehensive guides and schema generation. Add multiple documentation files covering authentication, error codes, rate limiting, and migration strategies. Update settings and URLs to support new documentation endpoints and schema configurations.

backend/igny8_core/settings.py

@@ -44,6 +44,7 @@ INSTALLED_APPS = [
     'rest_framework',
     'django_filters',
     'corsheaders',
+    'drf_spectacular',  # OpenAPI 3.0 schema generation
     'igny8_core.auth.apps.Igny8CoreAuthConfig',  # Use app config with custom label
     'igny8_core.ai.apps.AIConfig',  # AI Framework
     'igny8_core.modules.planner.apps.PlannerConfig',
@@ -245,6 +246,142 @@ REST_FRAMEWORK = {
         # Default fallback
         'default': '100/min',              # Default for endpoints without scope
     },
+    # OpenAPI Schema Generation (drf-spectacular)
+    'DEFAULT_SCHEMA_CLASS': 'drf_spectacular.openapi.AutoSchema',
+}
+
+# drf-spectacular Settings for OpenAPI 3.0 Schema Generation
+SPECTACULAR_SETTINGS = {
+    'TITLE': 'IGNY8 API v1.0',
+    'DESCRIPTION': '''
+    IGNY8 Unified API Standard v1.0
+    
+    A comprehensive REST API for content planning, creation, and management.
+    
+    ## Features
+    - **Unified Response Format**: All endpoints return consistent JSON structure
+    - **Layered Authorization**: Authentication → Tenant Access → Role → Site/Sector
+    - **Centralized Error Handling**: All errors wrapped in unified format
+    - **Scoped Rate Limiting**: Different limits for different operation types
+    - **Tenant Isolation**: All resources scoped by account/site/sector
+    - **Request Tracking**: Every request has a unique ID for debugging
+    
+    ## Authentication
+    All endpoints require JWT Bearer token authentication except:
+    - `POST /api/v1/auth/login/` - User login
+    - `POST /api/v1/auth/register/` - User registration
+    
+    Include token in Authorization header:
+    ```
+    Authorization: Bearer <your_access_token>
+    ```
+    
+    ## Response Format
+    All successful responses follow this format:
+    ```json
+    {
+      "success": true,
+      "data": {...},
+      "message": "Optional success message",
+      "request_id": "uuid"
+    }
+    ```
+    
+    All error responses follow this format:
+    ```json
+    {
+      "success": false,
+      "error": "Error message",
+      "errors": {
+        "field_name": ["Field-specific errors"]
+      },
+      "request_id": "uuid"
+    }
+    ```
+    
+    ## Rate Limiting
+    Rate limits are scoped by operation type. Check response headers:
+    - `X-Throttle-Limit`: Maximum requests allowed
+    - `X-Throttle-Remaining`: Remaining requests in current window
+    - `X-Throttle-Reset`: Time when limit resets (Unix timestamp)
+    
+    ## Pagination
+    List endpoints support pagination with query parameters:
+    - `page`: Page number (default: 1)
+    - `page_size`: Items per page (default: 10, max: 100)
+    
+    Paginated responses include:
+    ```json
+    {
+      "success": true,
+      "count": 100,
+      "next": "http://api.igny8.com/api/v1/endpoint/?page=2",
+      "previous": null,
+      "results": [...]
+    }
+    ```
+    ''',
+    'VERSION': '1.0.0',
+    'SERVE_INCLUDE_SCHEMA': False,
+    'SCHEMA_PATH_PREFIX': '/api/v1',
+    'COMPONENT_SPLIT_REQUEST': True,
+    'COMPONENT_NO_READ_ONLY_REQUIRED': True,
+    # Custom schema generator to include unified response format
+    'SCHEMA_GENERATOR_CLASS': 'drf_spectacular.generators.SchemaGenerator',
+    # Include request/response examples
+    'SERVE_PERMISSIONS': ['rest_framework.permissions.AllowAny'],
+    'SERVE_AUTHENTICATION': None,  # Allow unauthenticated access to docs
+    # Tags for grouping endpoints
+    'TAGS': [
+        {'name': 'Authentication', 'description': 'User authentication and registration'},
+        {'name': 'Planner', 'description': 'Keywords, clusters, and content ideas'},
+        {'name': 'Writer', 'description': 'Tasks, content, and images'},
+        {'name': 'System', 'description': 'Settings, prompts, and integrations'},
+        {'name': 'Billing', 'description': 'Credits, usage, and transactions'},
+    ],
+    # Custom response format documentation
+    'EXTENSIONS_INFO': {
+        'x-code-samples': [
+            {
+                'lang': 'Python',
+                'source': '''
+import requests
+
+headers = {
+    'Authorization': 'Bearer <your_token>',
+    'Content-Type': 'application/json'
+}
+
+response = requests.get('https://api.igny8.com/api/v1/planner/keywords/', headers=headers)
+data = response.json()
+
+if data['success']:
+    keywords = data['results']  # or data['data'] for single objects
+else:
+    print(f"Error: {data['error']}")
+                '''
+            },
+            {
+                'lang': 'JavaScript',
+                'source': '''
+const response = await fetch('https://api.igny8.com/api/v1/planner/keywords/', {
+    headers: {
+        'Authorization': 'Bearer <your_token>',
+        'Content-Type': 'application/json'
+    }
+});
+
+const data = await response.json();
+
+if (data.success) {
+    const keywords = data.results || data.data;
+} else {
+    console.error('Error:', data.error);
+}
+                '''
+            }
+        ]
+    }
 }
 
 # CORS Configuration