Improve estela generated OpenAPI documentation

Update swagger host in estela api settings. Add tags to estela api endpoints.
bitmakerla · Apr 17, 2023 · 3cc024c · 3cc024c
1 parent d14d7b3
commit 3cc024c
Show file tree

Hide file tree

Showing 22 changed files with 3,246 additions and 1,470 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):
@@ -149,6 +153,7 @@ def get_queryset(self):
 
     @swagger_auto_schema(
         responses={status.HTTP_200_OK: UserProfileSerializer()},
+        tags=["auth", "profile"],
     )
     def retrieve(self, request, *args, **kwargs):
         user: User = request.user
@@ -172,6 +177,7 @@ def retrieve(self, request, *args, **kwargs):
 
     @swagger_auto_schema(
         responses={status.HTTP_200_OK: UserProfileSerializer()},
+        tags=["auth", "profile"],
     )
     def update(self, request, *args, **kwargs):
         username = kwargs.get("username", "")
@@ -201,6 +207,7 @@ class ChangePasswordViewSet(viewsets.GenericViewSet):
     @swagger_auto_schema(
         request_body=ChangePasswordSerializer,
         responses={status.HTTP_200_OK: TokenSerializer()},
+        tags=["account"],
     )
     @action(
         methods=["PATCH"],
@@ -245,7 +252,9 @@ def get_parameters(self, request):
         return token, user_id
 
     @swagger_auto_schema(
-        methods=["POST"], responses={status.HTTP_200_OK: TokenSerializer()}
+        methods=["POST"],
+        responses={status.HTTP_200_OK: TokenSerializer()},
+        tags=["account"],
     )
     @action(
         methods=["POST"],
@@ -288,6 +297,7 @@ def request(self, request, *args, **kwargs):
                 },
             ),
         },
+        tags=["account"],
     )
     @action(methods=["GET"], detail=False)
     def validate(self, request, *args, **kwargs):
@@ -318,6 +328,7 @@ def validate(self, request, *args, **kwargs):
                 },
             ),
         },
+        tags=["account"],
     )
     @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=["project", "spider", "cronjob"],
     )
     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=["project", "spider", "cronjob"],
     )
     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=["project", "spider", "cronjob"],
     )
     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=["project", "spider", "cronjob"],
     )
     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=["project", "spider", "cronjob"],
     )
     @action(methods=["GET"], detail=True)
     def run_once(self, request, *args, **kwargs):

diff --git a/estela-api/api/views/deploy.py b/estela-api/api/views/deploy.py
@@ -40,6 +40,7 @@ def get_queryset(self):
     @swagger_auto_schema(
         request_body=DeployCreateSerializer,
         responses={status.HTTP_201_CREATED: DeployCreateSerializer()},
+        tags=["project", "deploy"],
     )
     def create(self, request, *args, **kwargs):
         project = get_object_or_404(Project, pid=self.kwargs["pid"])
@@ -74,6 +75,7 @@ def create(self, request, *args, **kwargs):
     @swagger_auto_schema(
         request_body=DeployUpdateSerializer,
         responses={status.HTTP_200_OK: DeployUpdateSerializer()},
+        tags=["project", "deploy"],
     )
     def update(self, request, *args, **kwargs):
         if not request.user.is_superuser:

diff --git a/estela-api/api/views/job.py b/estela-api/api/views/job.py
@@ -80,6 +80,7 @@ def get_queryset(self):
                 description="Job tag.",
             ),
         ],
+        tags=["project", "spider", "job"],
     )
     def list(self, *args, **kwargs):
         return super(SpiderJobViewSet, self).list(*args, **kwargs)
@@ -95,6 +96,7 @@ def list(self, *args, **kwargs):
         ],
         request_body=SpiderJobCreateSerializer,
         responses={status.HTTP_201_CREATED: SpiderJobCreateSerializer()},
+        tags=["project", "spider", "job"],
     )
     def create(self, request, *args, **kwargs):
         spider = get_object_or_404(Spider, sid=self.kwargs["sid"], deleted=False)
@@ -146,6 +148,7 @@ def create(self, request, *args, **kwargs):
     @swagger_auto_schema(
         request_body=SpiderJobUpdateSerializer,
         responses={status.HTTP_200_OK: SpiderJobUpdateSerializer()},
+        tags=["project", "spider", "job"],
     )
     def update(self, request, *args, **kwargs):
         partial = kwargs.pop("partial", False)

diff --git a/estela-api/api/views/job_data.py b/estela-api/api/views/job_data.py
@@ -85,6 +85,7 @@ def get_paginated_link(self, page_number):
                 required=False,
             ),
         ],
+        tags=["project", "spider", "job", "job-data"],
     )
     def list(self, request, *args, **kwargs):
         page, data_type, mode, page_size = self.get_parameters(request)
@@ -188,6 +189,7 @@ def list(self, request, *args, **kwargs):
                 required=True,
             ),
         ],
+        tags=["project", "spider", "job", "job-data"],
     )
     @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=["project"],
     )
     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=["project"],
     )
     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=["project"],
     )
     @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=["project"],
     )
     @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=["project"],
     )
     @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=["project"],
     )
     @action(methods=["GET"], detail=True)
     def usage(self, request, *args, **kwargs):

diff --git a/estela-api/api/views/spider.py b/estela-api/api/views/spider.py
@@ -26,6 +26,7 @@ def get_queryset(self):
     @swagger_auto_schema(
         request_body=SpiderUpdateSerializer,
         responses={status.HTTP_200_OK: SpiderUpdateSerializer()},
+        tags=["project", "spider"],
     )
     def update(self, request, *args, **kwargs):
         partial = kwargs.pop("partial", False)

diff --git a/estela-api/config/settings/base.py b/estela-api/config/settings/base.py
@@ -240,7 +240,7 @@
 SWAGGER_SETTINGS = {
     "DEFAULT_INFO": "docs.settings.api_info",
     "DEFAULT_GENERATOR_CLASS": "docs.settings.APISchemeGenerator",
-    "DEFAULT_API_URL": "http://127.0.0.1:8000",
+    "DEFAULT_API_URL": "https://api.cloud.bitmaker.dev/api/",
 }
 
 # AWS configurations