first commit

tasks/views.py

@@ -1,6 +1,13 @@
 from celery.result import AsyncResult
 
+from drf_spectacular.utils import (
+    OpenApiExample,
+    OpenApiResponse,
+    extend_schema,
+    inline_serializer,
+)
 from rest_framework import status
+from rest_framework import serializers as drf_serializers
 from rest_framework.response import Response
 from rest_framework.views import APIView
 
@@ -13,6 +20,46 @@ class TaskTriggerView(APIView):
     POST با بدنه اختیاری: {"duration": 3} - مدت زمان تسک به ثانیه.
     """
 
+    @extend_schema(
+        tags=["Tasks"],
+        summary="ثبت و اجرای تسک",
+        description="یک تسک نمونه را در صف Celery قرار می‌دهد.",
+        request=inline_serializer(
+            name="TaskTriggerRequest",
+            fields={
+                "duration": drf_serializers.IntegerField(
+                    required=False, default=1, help_text="مدت زمان تسک به ثانیه (۱–۶۰)"
+                ),
+            },
+        ),
+        responses={
+            200: inline_serializer(
+                name="TaskTriggerResponse",
+                fields={
+                    "code": drf_serializers.IntegerField(),
+                    "msg": drf_serializers.CharField(),
+                    "data": inline_serializer(
+                        name="TaskTriggerData",
+                        fields={
+                            "task_id": drf_serializers.CharField(),
+                        },
+                    ),
+                },
+            ),
+        },
+        examples=[
+            OpenApiExample(
+                "نمونه درخواست",
+                value={"duration": 3},
+                request_only=True,
+            ),
+            OpenApiExample(
+                "نمونه پاسخ",
+                value={"code": 200, "msg": "success", "data": {"task_id": "abc123-def456"}},
+                response_only=True,
+            ),
+        ],
+    )
     def post(self, request):
         duration = request.data.get("duration", 1)
         try:
@@ -33,6 +80,38 @@ class TaskStatusView(APIView):
     GET /api/tasks/<task_id>/status/
     """
 
+    @extend_schema(
+        tags=["Tasks"],
+        summary="وضعیت تسک",
+        description="وضعیت یک تسک Celery را بر اساس task_id برمی‌گرداند.",
+        responses={
+            200: inline_serializer(
+                name="TaskStatusResponse",
+                fields={
+                    "code": drf_serializers.IntegerField(),
+                    "msg": drf_serializers.CharField(),
+                    "data": inline_serializer(
+                        name="TaskStatusData",
+                        fields={
+                            "task_id": drf_serializers.CharField(),
+                            "status": drf_serializers.CharField(),
+                            "message": drf_serializers.CharField(required=False),
+                            "progress": drf_serializers.DictField(required=False),
+                            "result": drf_serializers.JSONField(required=False),
+                            "error": drf_serializers.CharField(required=False),
+                        },
+                    ),
+                },
+            ),
+        },
+        examples=[
+            OpenApiExample(
+                "تسک موفق",
+                value={"code": 200, "msg": "success", "data": {"task_id": "abc123", "status": "SUCCESS", "result": "done"}},
+                response_only=True,
+            ),
+        ],
+    )
     def get(self, request, task_id):
         result = AsyncResult(task_id)
         state = result.state