feat(api): полное API для всех парсеров с документацией

src/apps/core/views.py

@@ -13,6 +13,7 @@ from typing import Any
 
 from django.conf import settings
 from django.db import connection
+from drf_yasg.utils import swagger_auto_schema
 from rest_framework import status
 from rest_framework.permissions import AllowAny
 from rest_framework.request import Request
@@ -21,29 +22,29 @@ from rest_framework.views import APIView
 
 logger = logging.getLogger(__name__)
 
+# Swagger теги
+HEALTH_TAG = "Мониторинг"
+JOBS_TAG = "Фоновые задачи"
+
 
 class HealthCheckView(APIView):
     """
-    Comprehensive health check endpoint.
+    Комплексная проверка состояния системы.
 
-    GET /api/health/
-    Returns detailed status of all dependencies.
-
-    Response:
-    {
-        "status": "healthy" | "degraded" | "unhealthy",
-        "version": "1.0.0",
-        "checks": {
-            "database": {"status": "up", "latency_ms": 5},
-            "redis": {"status": "up", "latency_ms": 2},
-            "celery": {"status": "up"}
-        }
-    }
+    Возвращает статус всех зависимостей (БД, Redis, Celery).
     """
 
     permission_classes = [AllowAny]
     authentication_classes = []  # No auth required
 
+    @swagger_auto_schema(
+        tags=[HEALTH_TAG],
+        operation_summary="Проверка состояния",
+        operation_description=(
+            "Комплексная проверка всех зависимостей системы.\n"
+            "Возвращает статус: healthy, degraded или unhealthy."
+        ),
+    )
     def get(self, request: Request) -> Response:
         """Run all health checks and return status."""
         checks = {}
@@ -131,15 +132,19 @@ class HealthCheckView(APIView):
 
 class LivenessView(APIView):
     """
-    Kubernetes liveness probe endpoint.
+    Kubernetes liveness probe.
 
-    GET /api/health/live/
-    Returns 200 if the application is running.
+    Проверяет, запущено ли приложение.
     """
 
     permission_classes = [AllowAny]
     authentication_classes = []
 
+    @swagger_auto_schema(
+        tags=[HEALTH_TAG],
+        operation_summary="Liveness probe",
+        operation_description="Возвращает 200 если приложение запущено.",
+    )
     def get(self, request: Request) -> Response:
         """Simple liveness check."""
         return Response({"status": "alive"}, status=status.HTTP_200_OK)
@@ -147,15 +152,21 @@ class LivenessView(APIView):
 
 class ReadinessView(APIView):
     """
-    Kubernetes readiness probe endpoint.
+    Kubernetes readiness probe.
 
-    GET /api/health/ready/
-    Returns 200 if the application is ready to serve traffic.
+    Проверяет, готово ли приложение обрабатывать запросы.
     """
 
     permission_classes = [AllowAny]
     authentication_classes = []
 
+    @swagger_auto_schema(
+        tags=[HEALTH_TAG],
+        operation_summary="Readiness probe",
+        operation_description=(
+            "Возвращает 200 если приложение готово обрабатывать запросы."
+        ),
+    )
     def get(self, request: Request) -> Response:
         """Check if app is ready to serve traffic."""
         # Check database connection
@@ -177,26 +188,21 @@ class BackgroundJobStatusView(APIView):
     """
     Получение статуса фоновой задачи.
 
-    GET /api/v1/jobs/{task_id}/
     Возвращает статус, прогресс и результат задачи.
-
-    Response:
-    {
-        "id": "uuid",
-        "task_id": "celery-task-id",
-        "status": "pending|started|success|failure|revoked",
-        "progress": 75,
-        "progress_message": "Обработка данных...",
-        "result": {...},
-        "error": "",
-        "is_finished": false
-    }
     """
 
     from rest_framework.permissions import IsAuthenticated
 
     permission_classes = [IsAuthenticated]
 
+    @swagger_auto_schema(
+        tags=[JOBS_TAG],
+        operation_summary="Статус задачи",
+        operation_description=(
+            "Возвращает статус конкретной фоновой задачи.\n"
+            "Доступно только владельцу задачи или администратору."
+        ),
+    )
     def get(self, request: Request, task_id: str) -> Response:
         """Получить статус задачи по task_id."""
         from apps.core.serializers import BackgroundJobSerializer
@@ -219,18 +225,21 @@ class BackgroundJobListView(APIView):
     """
     Список фоновых задач пользователя.
 
-    GET /api/v1/jobs/
-    Возвращает список задач текущего пользователя.
-
-    Query params:
-        status: Фильтр по статусу (pending, started, success, failure)
-        limit: Количество записей (по умолчанию 50)
+    Возвращает список задач текущего пользователя с фильтрацией.
     """
 
     from rest_framework.permissions import IsAuthenticated
 
     permission_classes = [IsAuthenticated]
 
+    @swagger_auto_schema(
+        tags=[JOBS_TAG],
+        operation_summary="Список задач",
+        operation_description=(
+            "Возвращает список фоновых задач текущего пользователя.\n"
+            "Поддерживает фильтрацию по статусу (status) и лимит (limit)."
+        ),
+    )
     def get(self, request: Request) -> Response:
         """Получить список задач пользователя."""
         from apps.core.serializers import BackgroundJobListSerializer