Improve estela generated OpenAPI documentation

Add tags to estela api endpoints in current swagger_auto_schema decorator. Add tags for inherited methods from ModelViewSet and other mixins. Since in the past all of those were tagged just as `api`. Update `generated-api` code and `api.yaml` spec.
bitmakerla · May 5, 2023 · 14a3ed3 · 14a3ed3
1 parent cc803dd
commit 14a3ed3
Show file tree

Hide file tree

Showing 19 changed files with 2,735 additions and 2,402 deletions.
diff --git a/estela-api/api/views/auth.py b/estela-api/api/views/auth.py
@@ -47,7 +47,9 @@ def retry_send_verification_email(self, user, request):
             send_verification_email(user, request)
 
     @swagger_auto_schema(
-        methods=["POST"], responses={status.HTTP_200_OK: TokenSerializer()}
+        methods=["POST"],
+        responses={status.HTTP_200_OK: TokenSerializer()},
+        tags=["auth"],
     )
     @action(methods=["POST"], detail=False)
     def login(self, request, *args, **kwargs):
@@ -70,7 +72,9 @@ def login(self, request, *args, **kwargs):
         return Response(TokenSerializer(token).data)
 
     @swagger_auto_schema(
-        methods=["POST"], responses={status.HTTP_200_OK: TokenSerializer()}
+        methods=["POST"],
+        responses={status.HTTP_200_OK: TokenSerializer()},
+        tags=["auth"],
     )
     @action(methods=["POST"], detail=False, serializer_class=UserSerializer)
     def register(self, request, *args, **kwargs):
@@ -93,6 +97,9 @@ def register(self, request, *args, **kwargs):
         token, _ = Token.objects.get_or_create(user=user)
         return Response(TokenSerializer(token).data)
 
+    @swagger_auto_schema(
+        tags=["auth"],
+    )
     @action(methods=["GET"], detail=False)
     def activate(self, request, *args, **kwargs):
         token = request.query_params.get("token", "")
@@ -149,6 +156,7 @@ def get_queryset(self):
 
     @swagger_auto_schema(
         responses={status.HTTP_200_OK: UserProfileSerializer()},
+        tags=["auth"],
     )
     def retrieve(self, request, *args, **kwargs):
         user: User = request.user
@@ -172,6 +180,7 @@ def retrieve(self, request, *args, **kwargs):
 
     @swagger_auto_schema(
         responses={status.HTTP_200_OK: UserProfileSerializer()},
+        tags=["auth"],
     )
     def update(self, request, *args, **kwargs):
         username = kwargs.get("username", "")
@@ -196,11 +205,41 @@ def update(self, request, *args, **kwargs):
         serializer.save()
         return Response(data=serializer.data, status=status.HTTP_200_OK)
 
+    @swagger_auto_schema(
+        tags=["auth"],
+    )
+    def list(self, request, *args, **kwargs):
+        return super().list(request, *args, **kwargs)
+
+    @swagger_auto_schema(
+        responses={status.HTTP_201_CREATED: UserProfileSerializer()},
+        tags=["auth"],
+    )
+    def create(self, request, *args, **kwargs):
+        return super().create(request, *args, **kwargs)
+
+    @swagger_auto_schema(
+        responses={status.HTTP_200_OK: UserProfileSerializer()},
+        tags=["auth"],
+    )
+    def partial_update(self, request, *args, **kwargs):
+        return super().partial_update(request, *args, **kwargs)
+
+    @swagger_auto_schema(
+        responses={
+            status.HTTP_204_NO_CONTENT: openapi.Response("No Content"),
+        },
+        tags=["auth"],
+    )
+    def destroy(self, request, *args, **kwargs):
+        return super().destroy(request, *args, **kwargs)
+
 
 class ChangePasswordViewSet(viewsets.GenericViewSet):
     @swagger_auto_schema(
         request_body=ChangePasswordSerializer,
         responses={status.HTTP_200_OK: TokenSerializer()},
+        tags=["auth"],
     )
     @action(
         methods=["PATCH"],
@@ -245,14 +284,18 @@ def get_parameters(self, request):
         return token, user_id
 
     @swagger_auto_schema(
-        methods=["POST"], responses={status.HTTP_200_OK: TokenSerializer()}
+        operation_id="api_account_resetPassword_request",
+        methods=["POST"],
+        responses={status.HTTP_200_OK: TokenSerializer()},
+        tags=["auth"],
     )
     @action(
         methods=["POST"],
         detail=False,
         serializer_class=ResetPasswordRequestSerializer,
+        url_path="request",
     )
-    def request(self, request, *args, **kwargs):
+    def request_reset(self, request, *args, **kwargs):
         serializer = ResetPasswordRequestSerializer(data=request.data)
         serializer.is_valid(raise_exception=True)
         email = serializer.validated_data["email"]
@@ -288,6 +331,7 @@ def request(self, request, *args, **kwargs):
                 },
             ),
         },
+        tags=["auth"],
     )
     @action(methods=["GET"], detail=False)
     def validate(self, request, *args, **kwargs):
@@ -318,6 +362,7 @@ def validate(self, request, *args, **kwargs):
                 },
             ),
         },
+        tags=["auth"],
     )
     @action(
         methods=["PATCH"], detail=False, serializer_class=ResetPasswordConfirmSerializer

diff --git a/estela-api/api/views/cronjob.py b/estela-api/api/views/cronjob.py
@@ -56,13 +56,15 @@ def get_queryset(self):
                 description="Cron job tag.",
             ),
         ],
+        tags=["spider-cronjobs"],
     )
     def list(self, *args, **kwargs):
         return super(SpiderCronJobViewSet, self).list(*args, **kwargs)
 
     @swagger_auto_schema(
         request_body=SpiderCronJobCreateSerializer,
         responses={status.HTTP_201_CREATED: SpiderCronJobCreateSerializer()},
+        tags=["spider-cronjobs"],
     )
     def create(self, request, *args, **kwargs):
         spider = get_object_or_404(Spider, sid=self.kwargs["sid"], deleted=False)
@@ -101,6 +103,7 @@ def create(self, request, *args, **kwargs):
     @swagger_auto_schema(
         request_body=SpiderCronJobUpdateSerializer,
         responses={status.HTTP_200_OK: SpiderCronJobUpdateSerializer()},
+        tags=["spider-cronjobs"],
     )
     def update(self, request, *args, **kwargs):
         partial = kwargs.pop("partial", False)
@@ -118,6 +121,7 @@ def update(self, request, *args, **kwargs):
 
     @swagger_auto_schema(
         responses={status.HTTP_204_NO_CONTENT: "Cronjob deleted"},
+        tags=["spider-cronjobs"],
     )
     def destroy(self, request, *args, **kwargs):
         instance = self.get_object()
@@ -131,7 +135,9 @@ def perform_destroy(self, instance):
         instance.save()
 
     @swagger_auto_schema(
-        methods=["GET"], responses={status.HTTP_200_OK: SpiderCronJobSerializer()}
+        methods=["GET"],
+        responses={status.HTTP_200_OK: SpiderCronJobSerializer()},
+        tags=["spider-cronjobs"],
     )
     @action(methods=["GET"], detail=True)
     def run_once(self, request, *args, **kwargs):
@@ -142,3 +148,17 @@ def run_once(self, request, *args, **kwargs):
 
         run_cronjob_once(cronjob.data)
         return Response(cronjob.data, status=status.HTTP_200_OK)
+
+    @swagger_auto_schema(
+        responses={status.HTTP_200_OK: SpiderCronJobSerializer()},
+        tags=["spider-cronjobs"],
+    )
+    def retrieve(self, request, *args, **kwargs):
+        return super().retrieve(request, *args, **kwargs)
+
+    @swagger_auto_schema(
+        responses={status.HTTP_200_OK: SpiderCronJobSerializer()},
+        tags=["spider-cronjobs"],
+    )
+    def partial_update(self, request, *args, **kwargs):
+        return super().partial_update(request, *args, **kwargs)
diff --git a/estela-api/api/views/deploy.py b/estela-api/api/views/deploy.py
@@ -1,4 +1,5 @@
 from django.shortcuts import get_object_or_404
+from drf_yasg import openapi
 from drf_yasg.utils import swagger_auto_schema
 from rest_framework import viewsets, status
 from rest_framework.response import Response
@@ -40,6 +41,7 @@ def get_queryset(self):
     @swagger_auto_schema(
         request_body=DeployCreateSerializer,
         responses={status.HTTP_201_CREATED: DeployCreateSerializer()},
+        tags=["deploys"],
     )
     def create(self, request, *args, **kwargs):
         project = get_object_or_404(Project, pid=self.kwargs["pid"])
@@ -74,6 +76,7 @@ def create(self, request, *args, **kwargs):
     @swagger_auto_schema(
         request_body=DeployUpdateSerializer,
         responses={status.HTTP_200_OK: DeployUpdateSerializer()},
+        tags=["deploys"],
     )
     def update(self, request, *args, **kwargs):
         if not request.user.is_superuser:
@@ -93,3 +96,32 @@ def update(self, request, *args, **kwargs):
 
         headers = self.get_success_headers(serializer.data)
         return Response(serializer.data, status=status.HTTP_200_OK, headers=headers)
+
+    @swagger_auto_schema(
+        tags=["deploys"],
+    )
+    def list(self, request, *args, **kwargs):
+        return super().list(request, *args, **kwargs)
+
+    @swagger_auto_schema(
+        responses={status.HTTP_200_OK: DeploySerializer()},
+        tags=["deploys"],
+    )
+    def retrieve(self, request, *args, **kwargs):
+        return super().retrieve(request, *args, **kwargs)
+
+    @swagger_auto_schema(
+        responses={status.HTTP_200_OK: DeploySerializer()},
+        tags=["deploys"],
+    )
+    def partial_update(self, request, *args, **kwargs):
+        return super().partial_update(request, *args, **kwargs)
+
+    @swagger_auto_schema(
+        responses={
+            status.HTTP_204_NO_CONTENT: openapi.Response("No Content"),
+        },
+        tags=["deploys"],
+    )
+    def destroy(self, request, *args, **kwargs):
+        return super().destroy(request, *args, **kwargs)
diff --git a/estela-api/api/views/job.py b/estela-api/api/views/job.py
@@ -1,4 +1,3 @@
-from datetime import date, timedelta
 from django.shortcuts import get_object_or_404
 from django_filters.rest_framework import DjangoFilterBackend
 from drf_yasg.utils import swagger_auto_schema
@@ -80,6 +79,7 @@ def get_queryset(self):
                 description="Job tag.",
             ),
         ],
+        tags=["spider-jobs"],
     )
     def list(self, *args, **kwargs):
         return super(SpiderJobViewSet, self).list(*args, **kwargs)
@@ -95,6 +95,7 @@ def list(self, *args, **kwargs):
         ],
         request_body=SpiderJobCreateSerializer,
         responses={status.HTTP_201_CREATED: SpiderJobCreateSerializer()},
+        tags=["spider-jobs"],
     )
     def create(self, request, *args, **kwargs):
         spider = get_object_or_404(Spider, sid=self.kwargs["sid"], deleted=False)
@@ -146,6 +147,7 @@ def create(self, request, *args, **kwargs):
     @swagger_auto_schema(
         request_body=SpiderJobUpdateSerializer,
         responses={status.HTTP_200_OK: SpiderJobUpdateSerializer()},
+        tags=["spider-jobs"],
     )
     def update(self, request, *args, **kwargs):
         partial = kwargs.pop("partial", False)
@@ -161,3 +163,17 @@ def update(self, request, *args, **kwargs):
 
         headers = self.get_success_headers(serializer.data)
         return Response(serializer.data, status=status.HTTP_200_OK, headers=headers)
+
+    @swagger_auto_schema(
+        responses={status.HTTP_200_OK: SpiderJobSerializer()},
+        tags=["spider-jobs"],
+    )
+    def retrieve(self, request, *args, **kwargs):
+        return super().retrieve(request, *args, **kwargs)
+
+    @swagger_auto_schema(
+        responses={status.HTTP_200_OK: SpiderJobSerializer()},
+        tags=["spider-jobs"],
+    )
+    def partial_update(self, request, *args, **kwargs):
+        return super().partial_update(request, *args, **kwargs)
diff --git a/estela-api/api/views/job_data.py b/estela-api/api/views/job_data.py
@@ -84,6 +84,7 @@ def get_paginated_link(self, page_number):
                 required=False,
             ),
         ],
+        tags=["spider-jobs"],
     )
     def list(self, request, *args, **kwargs):
         page, data_type, page_size = self.get_parameters(request)
@@ -161,6 +162,7 @@ def list(self, request, *args, **kwargs):
                 required=True,
             ),
         ],
+        tags=["spider-jobs"],
     )
     @action(methods=["POST"], detail=False)
     def delete(self, request, *args, **kwargs):

diff --git a/estela-api/api/views/project.py b/estela-api/api/views/project.py
@@ -74,6 +74,7 @@ def perform_create(self, serializer):
     @swagger_auto_schema(
         request_body=ProjectUpdateSerializer,
         responses={status.HTTP_200_OK: ProjectUpdateSerializer()},
+        tags=["projects"],
     )
     def update(self, request, *args, **kwargs):
         partial = kwargs.pop("partial", False)
@@ -137,6 +138,7 @@ def update(self, request, *args, **kwargs):
 
     @swagger_auto_schema(
         responses={status.HTTP_204_NO_CONTENT: "Project deleted"},
+        tags=["projects"],
     )
     def destroy(self, request, *args, **kwargs):
         instance = self.get_object()
@@ -166,6 +168,7 @@ def perform_destroy(self, instance):
             ),
         ],
         responses={status.HTTP_200_OK: ProjectJobSerializer()},
+        tags=["projects"],
     )
     @action(methods=["GET"], detail=True)
     def jobs(self, request, *args, **kwargs):
@@ -205,6 +208,7 @@ def jobs(self, request, *args, **kwargs):
             ),
         ],
         responses={status.HTTP_200_OK: ProjectCronJobSerializer()},
+        tags=["projects"],
     )
     @action(methods=["GET"], detail=True)
     def cronjobs(self, request, *args, **kwargs):
@@ -227,6 +231,7 @@ def cronjobs(self, request, *args, **kwargs):
     @swagger_auto_schema(
         methods=["GET"],
         responses={status.HTTP_200_OK: ProjectUsageSerializer()},
+        tags=["projects"],
     )
     @action(methods=["GET"], detail=True)
     def current_usage(self, request, *args, **kwargs):
@@ -258,6 +263,7 @@ def current_usage(self, request, *args, **kwargs):
             ),
         ],
         responses={status.HTTP_200_OK: UsageRecordSerializer(many=True)},
+        tags=["projects"],
     )
     @action(methods=["GET"], detail=True)
     def usage(self, request, *args, **kwargs):
@@ -276,3 +282,30 @@ def usage(self, request, *args, **kwargs):
             serializer.data,
             status=status.HTTP_200_OK,
         )
+
+    @swagger_auto_schema(
+        tags=["projects"],
+    )
+    def list(self, request, *args, **kwargs):
+        return super().list(request, *args, **kwargs)
+
+    @swagger_auto_schema(
+        responses={status.HTTP_200_OK: ProjectSerializer()},
+        tags=["projects"],
+    )
+    def retrieve(self, request, *args, **kwargs):
+        return super().retrieve(request, *args, **kwargs)
+
+    @swagger_auto_schema(
+        responses={status.HTTP_201_CREATED: ProjectSerializer()},
+        tags=["projects"],
+    )
+    def create(self, request, *args, **kwargs):
+        return super().create(request, *args, **kwargs)
+
+    @swagger_auto_schema(
+        responses={status.HTTP_200_OK: ProjectSerializer()},
+        tags=["projects"],
+    )
+    def partial_update(self, request, *args, **kwargs):
+        return super().partial_update(request, *args, **kwargs)