UPDATE

location_data/serializers.py

@@ -73,4 +73,4 @@ class SoilDataTaskResponseSerializer(serializers.Serializer):
     task_id = serializers.CharField()
     lon = serializers.FloatField(source="longitude")
     lat = serializers.FloatField(source="latitude")
-    status_url = serializers.URLField(required=False)
+    status_url = serializers.CharField(required=False)

location_data/views.py

@@ -9,15 +9,50 @@ from rest_framework import serializers as drf_serializers
 from rest_framework.response import Response
 from rest_framework.views import APIView
 
+from config.openapi import (
+    build_envelope_serializer,
+    build_response,
+    build_task_status_data_serializer,
+)
 from .models import SoilLocation
 from .serializers import (
     SoilDataRequestSerializer,
+    SoilDepthDataSerializer,
     SoilDataTaskResponseSerializer,
     SoilLocationResponseSerializer,
 )
 from .tasks import fetch_soil_data_task
 
 
+SoilLocationPayloadSerializer = inline_serializer(
+    name="SoilLocationPayloadSerializer",
+    fields={
+        "source": drf_serializers.CharField(),
+        "id": drf_serializers.IntegerField(),
+        "lon": drf_serializers.DecimalField(max_digits=9, decimal_places=6),
+        "lat": drf_serializers.DecimalField(max_digits=9, decimal_places=6),
+        "depths": SoilDepthDataSerializer(many=True),
+    },
+)
+SoilDataResponseSerializer = build_envelope_serializer(
+    "SoilDataResponseSerializer",
+    SoilLocationPayloadSerializer,
+)
+SoilTaskQueuedResponseSerializer = build_envelope_serializer(
+    "SoilTaskQueuedResponseSerializer",
+    SoilDataTaskResponseSerializer,
+)
+SoilErrorResponseSerializer = build_envelope_serializer(
+    "SoilErrorResponseSerializer",
+    data_required=False,
+    allow_null=True,
+)
+SoilTaskStatusResponseSerializer = build_envelope_serializer(
+    "SoilTaskStatusResponseSerializer",
+    build_task_status_data_serializer("SoilTaskStatusDataSerializer"),
+)
+
+
 class SoilDataView(APIView):
     """
     API خاک: مختصات جغرافیایی را می‌گیرد.
@@ -49,9 +84,18 @@ class SoilDataView(APIView):
             },
         ],
         responses={
-            200: OpenApiResponse(description="داده خاک از دیتابیس"),
-            202: OpenApiResponse(description="تسک در صف قرار گرفت"),
-            400: OpenApiResponse(description="داده نامعتبر"),
+            200: build_response(
+                SoilDataResponseSerializer,
+                "داده خاک از دیتابیس بازگردانده شد.",
+            ),
+            202: build_response(
+                SoilTaskQueuedResponseSerializer,
+                "تسک واکشی داده خاک در صف قرار گرفت.",
+            ),
+            400: build_response(
+                SoilErrorResponseSerializer,
+                "پارامترهای ورودی نامعتبر هستند.",
+            ),
         },
     )
     def get(self, request):
@@ -63,9 +107,18 @@ class SoilDataView(APIView):
         description="با ارسال lat و lon در بدنه، داده خاک از DB یا از طریق تسک Celery برگردانده می‌شود.",
         request=SoilDataRequestSerializer,
         responses={
-            200: OpenApiResponse(description="داده خاک از دیتابیس"),
-            202: OpenApiResponse(description="تسک در صف قرار گرفت"),
-            400: OpenApiResponse(description="داده نامعتبر"),
+            200: build_response(
+                SoilDataResponseSerializer,
+                "داده خاک از دیتابیس بازگردانده شد.",
+            ),
+            202: build_response(
+                SoilTaskQueuedResponseSerializer,
+                "تسک واکشی داده خاک در صف قرار گرفت.",
+            ),
+            400: build_response(
+                SoilErrorResponseSerializer,
+                "پارامترهای ورودی نامعتبر هستند.",
+            ),
         },
         examples=[
             OpenApiExample(
@@ -141,23 +194,9 @@ class SoilDataTaskStatusView(APIView):
         summary="وضعیت تسک داده خاک",
         description="وضعیت تسک Celery واکشی داده خاک را برمی‌گرداند.",
         responses={
-            200: inline_serializer(
-                name="SoilTaskStatusResponse",
-                fields={
-                    "code": drf_serializers.IntegerField(),
-                    "msg": drf_serializers.CharField(),
-                    "data": inline_serializer(
-                        name="SoilTaskStatusData",
-                        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),
-                        },
-                    ),
-                },
+            200: build_response(
+                SoilTaskStatusResponseSerializer,
+                "وضعیت فعلی تسک واکشی داده خاک.",
             ),
         },
     )