416 lines
13 KiB
Python
416 lines
13 KiB
Python
"""OpenAPI documentation configuration for my-uploader-bot API."""
|
|
|
|
from typing import Dict, Any
|
|
|
|
# API metadata
|
|
API_TITLE = "My Uploader Bot API"
|
|
API_VERSION = "2.0.0"
|
|
API_DESCRIPTION = """
|
|
# My Uploader Bot API
|
|
|
|
A comprehensive file upload and management system with blockchain integration.
|
|
|
|
## Features
|
|
|
|
- **File Upload & Management**: Chunked uploads, multiple storage backends, file processing
|
|
- **User Authentication**: JWT tokens, API keys, sessions management
|
|
- **Blockchain Integration**: TON blockchain wallet management, transactions
|
|
- **Content Management**: Version control, metadata, search functionality
|
|
- **Security**: Rate limiting, CORS, input validation, file encryption
|
|
- **Monitoring**: Prometheus metrics, structured logging, health checks
|
|
|
|
## Authentication
|
|
|
|
The API supports multiple authentication methods:
|
|
|
|
1. **JWT Bearer Token**: Use `Authorization: Bearer <token>` header
|
|
2. **API Key**: Use `X-API-Key: <api_key>` header
|
|
3. **Session Cookie**: Browser-based authentication
|
|
|
|
## Rate Limiting
|
|
|
|
API endpoints are rate-limited based on user tier:
|
|
- Free tier: 100 requests per hour
|
|
- Premium tier: 1000 requests per hour
|
|
- Enterprise tier: 10000 requests per hour
|
|
|
|
## File Upload Process
|
|
|
|
1. **Initiate Upload**: POST `/api/v1/storage/upload/initiate` with file metadata
|
|
2. **Upload Chunks**: POST `/api/v1/storage/upload/chunk` for each chunk
|
|
3. **Complete Upload**: POST `/api/v1/storage/upload/complete` to finalize
|
|
4. **Processing**: File is automatically processed in the background
|
|
|
|
## Error Handling
|
|
|
|
All errors follow RFC 7807 Problem Details format:
|
|
|
|
```json
|
|
{
|
|
"type": "https://api.myuploader.com/errors/validation",
|
|
"title": "Validation Error",
|
|
"status": 422,
|
|
"detail": "The request body contains invalid data",
|
|
"instance": "/api/v1/content/upload",
|
|
"errors": [
|
|
{
|
|
"field": "file_size",
|
|
"message": "File size exceeds maximum limit"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
## Webhook Events
|
|
|
|
The API can send webhook notifications for:
|
|
- File upload completion
|
|
- Processing status updates
|
|
- Blockchain transaction confirmations
|
|
- User subscription changes
|
|
|
|
## SDKs and Examples
|
|
|
|
- Python SDK: `pip install myuploader-python`
|
|
- JavaScript SDK: `npm install @myuploader/js-sdk`
|
|
- Examples: https://github.com/myuploader/examples
|
|
|
|
## Support
|
|
|
|
- Documentation: https://docs.myuploader.com
|
|
- Support: support@myuploader.com
|
|
- Status: https://status.myuploader.com
|
|
"""
|
|
|
|
# OpenAPI tags
|
|
TAGS_METADATA = [
|
|
{
|
|
"name": "Authentication",
|
|
"description": "User authentication and session management endpoints",
|
|
},
|
|
{
|
|
"name": "Users",
|
|
"description": "User profile and account management",
|
|
},
|
|
{
|
|
"name": "Content",
|
|
"description": "Content management, search, and metadata operations",
|
|
},
|
|
{
|
|
"name": "Storage",
|
|
"description": "File upload, download, and storage operations",
|
|
},
|
|
{
|
|
"name": "Blockchain",
|
|
"description": "TON blockchain wallet and transaction management",
|
|
},
|
|
{
|
|
"name": "System",
|
|
"description": "System health, metrics, and administrative endpoints",
|
|
},
|
|
]
|
|
|
|
# Response examples
|
|
RESPONSE_EXAMPLES = {
|
|
"user_profile": {
|
|
"summary": "User profile example",
|
|
"value": {
|
|
"id": "123e4567-e89b-12d3-a456-426614174000",
|
|
"username": "john_doe",
|
|
"email": "john@example.com",
|
|
"first_name": "John",
|
|
"last_name": "Doe",
|
|
"is_active": True,
|
|
"is_verified": True,
|
|
"avatar_url": "https://cdn.myuploader.com/avatars/john_doe.jpg",
|
|
"bio": "Software developer and blockchain enthusiast",
|
|
"created_at": "2024-01-01T00:00:00Z",
|
|
"updated_at": "2024-01-01T00:00:00Z"
|
|
}
|
|
},
|
|
"content_item": {
|
|
"summary": "Content item example",
|
|
"value": {
|
|
"id": "123e4567-e89b-12d3-a456-426614174001",
|
|
"title": "My Awesome Video",
|
|
"description": "A great video about blockchain development",
|
|
"content_type": "video",
|
|
"file_path": "uploads/user123/video_2024_01_01.mp4",
|
|
"file_size": 104857600,
|
|
"mime_type": "video/mp4",
|
|
"is_public": True,
|
|
"view_count": 1250,
|
|
"download_count": 95,
|
|
"like_count": 42,
|
|
"tags": ["blockchain", "tutorial", "development"],
|
|
"thumbnail_url": "https://cdn.myuploader.com/thumbnails/video_thumb.jpg",
|
|
"status": "published",
|
|
"created_at": "2024-01-01T00:00:00Z",
|
|
"updated_at": "2024-01-01T00:00:00Z"
|
|
}
|
|
},
|
|
"upload_session": {
|
|
"summary": "Upload session example",
|
|
"value": {
|
|
"session_id": "upload_123e4567-e89b-12d3-a456-426614174002",
|
|
"filename": "large_video.mp4",
|
|
"file_size": 1073741824,
|
|
"chunk_size": 1048576,
|
|
"total_chunks": 1024,
|
|
"uploaded_chunks": 512,
|
|
"status": "uploading",
|
|
"progress": 50.0,
|
|
"expires_at": "2024-01-01T01:00:00Z",
|
|
"upload_urls": [
|
|
"https://api.myuploader.com/api/v1/storage/upload/chunk"
|
|
]
|
|
}
|
|
},
|
|
"wallet_info": {
|
|
"summary": "Wallet information example",
|
|
"value": {
|
|
"id": "123e4567-e89b-12d3-a456-426614174003",
|
|
"address": "EQD6M8aVGx1fF6Z5q5q5q5q5q5q5q5q5q5q5q5q5q5q5q5q5q",
|
|
"network": "mainnet",
|
|
"balance": "10.50000000",
|
|
"is_active": True,
|
|
"is_primary": True,
|
|
"created_at": "2024-01-01T00:00:00Z",
|
|
"transactions": [
|
|
{
|
|
"tx_hash": "abc123def456ghi789jkl012mno345pqr678stu901vwx234yz",
|
|
"amount": "5.00000000",
|
|
"status": "confirmed",
|
|
"created_at": "2024-01-01T00:30:00Z"
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"error_validation": {
|
|
"summary": "Validation error example",
|
|
"value": {
|
|
"type": "https://api.myuploader.com/errors/validation",
|
|
"title": "Validation Error",
|
|
"status": 422,
|
|
"detail": "The request contains invalid data",
|
|
"instance": "/api/v1/content/upload",
|
|
"errors": [
|
|
{
|
|
"field": "file_size",
|
|
"message": "File size must be less than 100MB"
|
|
},
|
|
{
|
|
"field": "content_type",
|
|
"message": "Content type is required"
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"error_auth": {
|
|
"summary": "Authentication error example",
|
|
"value": {
|
|
"type": "https://api.myuploader.com/errors/authentication",
|
|
"title": "Authentication Required",
|
|
"status": 401,
|
|
"detail": "Valid authentication credentials are required",
|
|
"instance": "/api/v1/content/private"
|
|
}
|
|
},
|
|
"error_forbidden": {
|
|
"summary": "Permission error example",
|
|
"value": {
|
|
"type": "https://api.myuploader.com/errors/forbidden",
|
|
"title": "Insufficient Permissions",
|
|
"status": 403,
|
|
"detail": "You don't have permission to access this resource",
|
|
"instance": "/api/v1/admin/users"
|
|
}
|
|
},
|
|
"error_not_found": {
|
|
"summary": "Not found error example",
|
|
"value": {
|
|
"type": "https://api.myuploader.com/errors/not-found",
|
|
"title": "Resource Not Found",
|
|
"status": 404,
|
|
"detail": "The requested resource was not found",
|
|
"instance": "/api/v1/content/nonexistent-id"
|
|
}
|
|
},
|
|
"error_rate_limit": {
|
|
"summary": "Rate limit error example",
|
|
"value": {
|
|
"type": "https://api.myuploader.com/errors/rate-limit",
|
|
"title": "Rate Limit Exceeded",
|
|
"status": 429,
|
|
"detail": "Too many requests. Please try again later",
|
|
"instance": "/api/v1/content/search",
|
|
"retry_after": 60
|
|
}
|
|
}
|
|
}
|
|
|
|
# Security schemes
|
|
SECURITY_SCHEMES = {
|
|
"BearerAuth": {
|
|
"type": "http",
|
|
"scheme": "bearer",
|
|
"bearerFormat": "JWT",
|
|
"description": "JWT token authentication. Get token from /api/v1/auth/login"
|
|
},
|
|
"ApiKeyAuth": {
|
|
"type": "apiKey",
|
|
"in": "header",
|
|
"name": "X-API-Key",
|
|
"description": "API key authentication. Get API key from user dashboard"
|
|
},
|
|
"CookieAuth": {
|
|
"type": "apiKey",
|
|
"in": "cookie",
|
|
"name": "session",
|
|
"description": "Session cookie authentication"
|
|
}
|
|
}
|
|
|
|
# OpenAPI configuration
|
|
def get_openapi_config() -> Dict[str, Any]:
|
|
"""Get OpenAPI configuration."""
|
|
return {
|
|
"title": API_TITLE,
|
|
"version": API_VERSION,
|
|
"description": API_DESCRIPTION,
|
|
"terms_of_service": "https://myuploader.com/terms",
|
|
"contact": {
|
|
"name": "My Uploader Bot Support",
|
|
"url": "https://myuploader.com/support",
|
|
"email": "support@myuploader.com"
|
|
},
|
|
"license": {
|
|
"name": "MIT License",
|
|
"url": "https://opensource.org/licenses/MIT"
|
|
},
|
|
"servers": [
|
|
{
|
|
"url": "https://api.myuploader.com",
|
|
"description": "Production server"
|
|
},
|
|
{
|
|
"url": "https://staging-api.myuploader.com",
|
|
"description": "Staging server"
|
|
},
|
|
{
|
|
"url": "http://localhost:8000",
|
|
"description": "Development server"
|
|
}
|
|
],
|
|
"tags": TAGS_METADATA,
|
|
"components": {
|
|
"securitySchemes": SECURITY_SCHEMES,
|
|
"examples": RESPONSE_EXAMPLES,
|
|
"responses": {
|
|
"ValidationError": {
|
|
"description": "Validation error response",
|
|
"content": {
|
|
"application/json": {
|
|
"example": RESPONSE_EXAMPLES["error_validation"]["value"]
|
|
}
|
|
}
|
|
},
|
|
"AuthError": {
|
|
"description": "Authentication error response",
|
|
"content": {
|
|
"application/json": {
|
|
"example": RESPONSE_EXAMPLES["error_auth"]["value"]
|
|
}
|
|
}
|
|
},
|
|
"ForbiddenError": {
|
|
"description": "Permission error response",
|
|
"content": {
|
|
"application/json": {
|
|
"example": RESPONSE_EXAMPLES["error_forbidden"]["value"]
|
|
}
|
|
}
|
|
},
|
|
"NotFoundError": {
|
|
"description": "Not found error response",
|
|
"content": {
|
|
"application/json": {
|
|
"example": RESPONSE_EXAMPLES["error_not_found"]["value"]
|
|
}
|
|
}
|
|
},
|
|
"RateLimitError": {
|
|
"description": "Rate limit error response",
|
|
"content": {
|
|
"application/json": {
|
|
"example": RESPONSE_EXAMPLES["error_rate_limit"]["value"]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"security": [
|
|
{"BearerAuth": []},
|
|
{"ApiKeyAuth": []},
|
|
{"CookieAuth": []}
|
|
]
|
|
}
|
|
|
|
|
|
# Custom OpenAPI schema
|
|
CUSTOM_OPENAPI_SCHEMA = {
|
|
"x-logo": {
|
|
"url": "https://myuploader.com/logo.png",
|
|
"altText": "My Uploader Bot Logo"
|
|
},
|
|
"x-code-samples": [
|
|
{
|
|
"lang": "Python",
|
|
"source": """
|
|
import requests
|
|
|
|
# Upload a file
|
|
response = requests.post(
|
|
'https://api.myuploader.com/api/v1/storage/upload/initiate',
|
|
headers={'Authorization': 'Bearer <your_token>'},
|
|
json={
|
|
'filename': 'example.jpg',
|
|
'file_size': 1024000,
|
|
'content_type': 'image'
|
|
}
|
|
)
|
|
"""
|
|
},
|
|
{
|
|
"lang": "JavaScript",
|
|
"source": """
|
|
// Upload a file
|
|
const response = await fetch('https://api.myuploader.com/api/v1/storage/upload/initiate', {
|
|
method: 'POST',
|
|
headers: {
|
|
'Authorization': 'Bearer <your_token>',
|
|
'Content-Type': 'application/json'
|
|
},
|
|
body: JSON.stringify({
|
|
filename: 'example.jpg',
|
|
file_size: 1024000,
|
|
content_type: 'image'
|
|
})
|
|
});
|
|
"""
|
|
},
|
|
{
|
|
"lang": "cURL",
|
|
"source": """
|
|
curl -X POST https://api.myuploader.com/api/v1/storage/upload/initiate \\
|
|
-H "Authorization: Bearer <your_token>" \\
|
|
-H "Content-Type: application/json" \\
|
|
-d '{
|
|
"filename": "example.jpg",
|
|
"file_size": 1024000,
|
|
"content_type": "image"
|
|
}'
|
|
"""
|
|
}
|
|
]
|
|
} |