improve swagger docs

Author: korgan00

gateway/api/v1/views/jobs.py

@@ -2,6 +2,7 @@
 Jobs view api for V1.
 """
 
+from drf_yasg import openapi
 from drf_yasg.utils import swagger_auto_schema
 from rest_framework import permissions, status
 from rest_framework.decorators import action
@@ -72,6 +73,64 @@ def result(self, request, pk=None):
 
     @swagger_auto_schema(
         operation_description="Update the sub status of a job",
+        request_body=openapi.Schema(
+            type=openapi.TYPE_OBJECT,
+            required=["sub_status"],
+            properties={
+                "sub_status": openapi.Schema(type=openapi.TYPE_STRING)
+            },
+            description="Value to populate the sub-status of a Job"
+        ),
+        responses={
+            status.HTTP_200_OK: openapi.Response(
+                description="In case everything is ok.",
+                schema=openapi.Schema(
+                    type=openapi.TYPE_OBJECT,
+                    properties={
+                        "message": openapi.Schema(
+                            type=openapi.TYPE_STRING,
+                            example="Sub status updated correctly"
+                        )
+                    }
+                )
+            ),
+            status.HTTP_400_BAD_REQUEST: openapi.Response(
+                description="In case your request doesnt have a valid 'sub_status'.",
+                schema=openapi.Schema(
+                    type=openapi.TYPE_OBJECT,
+                    properties={
+                        "message": openapi.Schema(
+                            type=openapi.TYPE_STRING,
+                            example="'sub_status' not provided or is not valid"
+                        )
+                    }
+                )
+            ),
+            status.HTTP_403_FORBIDDEN: openapi.Response(
+                description="In case you cannot change the sub_status.",
+                schema=openapi.Schema(
+                    type=openapi.TYPE_OBJECT,
+                    properties={
+                        "message": openapi.Schema(
+                            type=openapi.TYPE_STRING,
+                            example="Cannot update 'sub_status' when is not  in RUNNING status. (Currently PENDING)"
+                        )
+                    }
+                )
+            ),
+            status.HTTP_404_NOT_FOUND: openapi.Response(
+                description="In case the job doesnt exist or you dont have access to it.",
+                schema=openapi.Schema(
+                    type=openapi.TYPE_OBJECT,
+                    properties={
+                        "message": openapi.Schema(
+                            type=openapi.TYPE_STRING,
+                            example="Job [XXXX] not found"
+                        )
+                    }
+                )
+            )
+        },
     )
     @action(methods=["POST"], detail=True)
     def sub_status(self, request, pk=None):