Skip to content

Commit 14a3ed3

Browse files
johann2357johann2357
committed
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.
1 parent cc803dd commit 14a3ed3

File tree

19 files changed

+2735
-2402
lines changed

19 files changed

+2735
-2402
lines changed

‎estela-api/api/views/auth.py‎

Lines changed: 49 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,9 @@ def retry_send_verification_email(self, user, request):
4747
send_verification_email(user, request)
4848

4949
@swagger_auto_schema(
50-
methods=["POST"], responses={status.HTTP_200_OK: TokenSerializer()}
50+
methods=["POST"],
51+
responses={status.HTTP_200_OK: TokenSerializer()},
52+
tags=["auth"],
5153
)
5254
@action(methods=["POST"], detail=False)
5355
def login(self, request, *args, **kwargs):
@@ -70,7 +72,9 @@ def login(self, request, *args, **kwargs):
7072
return Response(TokenSerializer(token).data)
7173

7274
@swagger_auto_schema(
73-
methods=["POST"], responses={status.HTTP_200_OK: TokenSerializer()}
75+
methods=["POST"],
76+
responses={status.HTTP_200_OK: TokenSerializer()},
77+
tags=["auth"],
7478
)
7579
@action(methods=["POST"], detail=False, serializer_class=UserSerializer)
7680
def register(self, request, *args, **kwargs):
@@ -93,6 +97,9 @@ def register(self, request, *args, **kwargs):
9397
token, _ = Token.objects.get_or_create(user=user)
9498
return Response(TokenSerializer(token).data)
9599

100+
@swagger_auto_schema(
101+
tags=["auth"],
102+
)
96103
@action(methods=["GET"], detail=False)
97104
def activate(self, request, *args, **kwargs):
98105
token = request.query_params.get("token", "")
@@ -149,6 +156,7 @@ def get_queryset(self):
149156

150157
@swagger_auto_schema(
151158
responses={status.HTTP_200_OK: UserProfileSerializer()},
159+
tags=["auth"],
152160
)
153161
def retrieve(self, request, *args, **kwargs):
154162
user: User = request.user
@@ -172,6 +180,7 @@ def retrieve(self, request, *args, **kwargs):
172180

173181
@swagger_auto_schema(
174182
responses={status.HTTP_200_OK: UserProfileSerializer()},
183+
tags=["auth"],
175184
)
176185
def update(self, request, *args, **kwargs):
177186
username = kwargs.get("username", "")
@@ -196,11 +205,41 @@ def update(self, request, *args, **kwargs):
196205
serializer.save()
197206
return Response(data=serializer.data, status=status.HTTP_200_OK)
198207

208+
@swagger_auto_schema(
209+
tags=["auth"],
210+
)
211+
def list(self, request, *args, **kwargs):
212+
return super().list(request, *args, **kwargs)
213+
214+
@swagger_auto_schema(
215+
responses={status.HTTP_201_CREATED: UserProfileSerializer()},
216+
tags=["auth"],
217+
)
218+
def create(self, request, *args, **kwargs):
219+
return super().create(request, *args, **kwargs)
220+
221+
@swagger_auto_schema(
222+
responses={status.HTTP_200_OK: UserProfileSerializer()},
223+
tags=["auth"],
224+
)
225+
def partial_update(self, request, *args, **kwargs):
226+
return super().partial_update(request, *args, **kwargs)
227+
228+
@swagger_auto_schema(
229+
responses={
230+
status.HTTP_204_NO_CONTENT: openapi.Response("No Content"),
231+
},
232+
tags=["auth"],
233+
)
234+
def destroy(self, request, *args, **kwargs):
235+
return super().destroy(request, *args, **kwargs)
236+
199237

200238
class ChangePasswordViewSet(viewsets.GenericViewSet):
201239
@swagger_auto_schema(
202240
request_body=ChangePasswordSerializer,
203241
responses={status.HTTP_200_OK: TokenSerializer()},
242+
tags=["auth"],
204243
)
205244
@action(
206245
methods=["PATCH"],
@@ -245,14 +284,18 @@ def get_parameters(self, request):
245284
return token, user_id
246285

247286
@swagger_auto_schema(
248-
methods=["POST"], responses={status.HTTP_200_OK: TokenSerializer()}
287+
operation_id="api_account_resetPassword_request",
288+
methods=["POST"],
289+
responses={status.HTTP_200_OK: TokenSerializer()},
290+
tags=["auth"],
249291
)
250292
@action(
251293
methods=["POST"],
252294
detail=False,
253295
serializer_class=ResetPasswordRequestSerializer,
296+
url_path="request",
254297
)
255-
def request(self, request, *args, **kwargs):
298+
def request_reset(self, request, *args, **kwargs):
256299
serializer = ResetPasswordRequestSerializer(data=request.data)
257300
serializer.is_valid(raise_exception=True)
258301
email = serializer.validated_data["email"]
@@ -288,6 +331,7 @@ def request(self, request, *args, **kwargs):
288331
},
289332
),
290333
},
334+
tags=["auth"],
291335
)
292336
@action(methods=["GET"], detail=False)
293337
def validate(self, request, *args, **kwargs):
@@ -318,6 +362,7 @@ def validate(self, request, *args, **kwargs):
318362
},
319363
),
320364
},
365+
tags=["auth"],
321366
)
322367
@action(
323368
methods=["PATCH"], detail=False, serializer_class=ResetPasswordConfirmSerializer

‎estela-api/api/views/cronjob.py‎

Lines changed: 21 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -56,13 +56,15 @@ def get_queryset(self):
5656
description="Cron job tag.",
5757
),
5858
],
59+
tags=["spider-cronjobs"],
5960
)
6061
def list(self, *args, **kwargs):
6162
return super(SpiderCronJobViewSet, self).list(*args, **kwargs)
6263

6364
@swagger_auto_schema(
6465
request_body=SpiderCronJobCreateSerializer,
6566
responses={status.HTTP_201_CREATED: SpiderCronJobCreateSerializer()},
67+
tags=["spider-cronjobs"],
6668
)
6769
def create(self, request, *args, **kwargs):
6870
spider = get_object_or_404(Spider, sid=self.kwargs["sid"], deleted=False)
@@ -101,6 +103,7 @@ def create(self, request, *args, **kwargs):
101103
@swagger_auto_schema(
102104
request_body=SpiderCronJobUpdateSerializer,
103105
responses={status.HTTP_200_OK: SpiderCronJobUpdateSerializer()},
106+
tags=["spider-cronjobs"],
104107
)
105108
def update(self, request, *args, **kwargs):
106109
partial = kwargs.pop("partial", False)
@@ -118,6 +121,7 @@ def update(self, request, *args, **kwargs):
118121

119122
@swagger_auto_schema(
120123
responses={status.HTTP_204_NO_CONTENT: "Cronjob deleted"},
124+
tags=["spider-cronjobs"],
121125
)
122126
def destroy(self, request, *args, **kwargs):
123127
instance = self.get_object()
@@ -131,7 +135,9 @@ def perform_destroy(self, instance):
131135
instance.save()
132136

133137
@swagger_auto_schema(
134-
methods=["GET"], responses={status.HTTP_200_OK: SpiderCronJobSerializer()}
138+
methods=["GET"],
139+
responses={status.HTTP_200_OK: SpiderCronJobSerializer()},
140+
tags=["spider-cronjobs"],
135141
)
136142
@action(methods=["GET"], detail=True)
137143
def run_once(self, request, *args, **kwargs):
@@ -142,3 +148,17 @@ def run_once(self, request, *args, **kwargs):
142148

143149
run_cronjob_once(cronjob.data)
144150
return Response(cronjob.data, status=status.HTTP_200_OK)
151+
152+
@swagger_auto_schema(
153+
responses={status.HTTP_200_OK: SpiderCronJobSerializer()},
154+
tags=["spider-cronjobs"],
155+
)
156+
def retrieve(self, request, *args, **kwargs):
157+
return super().retrieve(request, *args, **kwargs)
158+
159+
@swagger_auto_schema(
160+
responses={status.HTTP_200_OK: SpiderCronJobSerializer()},
161+
tags=["spider-cronjobs"],
162+
)
163+
def partial_update(self, request, *args, **kwargs):
164+
return super().partial_update(request, *args, **kwargs)

‎estela-api/api/views/deploy.py‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
from django.shortcuts import get_object_or_404
2+
from drf_yasg import openapi
23
from drf_yasg.utils import swagger_auto_schema
34
from rest_framework import viewsets, status
45
from rest_framework.response import Response
@@ -40,6 +41,7 @@ def get_queryset(self):
4041
@swagger_auto_schema(
4142
request_body=DeployCreateSerializer,
4243
responses={status.HTTP_201_CREATED: DeployCreateSerializer()},
44+
tags=["deploys"],
4345
)
4446
def create(self, request, *args, **kwargs):
4547
project = get_object_or_404(Project, pid=self.kwargs["pid"])
@@ -74,6 +76,7 @@ def create(self, request, *args, **kwargs):
7476
@swagger_auto_schema(
7577
request_body=DeployUpdateSerializer,
7678
responses={status.HTTP_200_OK: DeployUpdateSerializer()},
79+
tags=["deploys"],
7780
)
7881
def update(self, request, *args, **kwargs):
7982
if not request.user.is_superuser:
@@ -93,3 +96,32 @@ def update(self, request, *args, **kwargs):
9396

9497
headers = self.get_success_headers(serializer.data)
9598
return Response(serializer.data, status=status.HTTP_200_OK, headers=headers)
99+
100+
@swagger_auto_schema(
101+
tags=["deploys"],
102+
)
103+
def list(self, request, *args, **kwargs):
104+
return super().list(request, *args, **kwargs)
105+
106+
@swagger_auto_schema(
107+
responses={status.HTTP_200_OK: DeploySerializer()},
108+
tags=["deploys"],
109+
)
110+
def retrieve(self, request, *args, **kwargs):
111+
return super().retrieve(request, *args, **kwargs)
112+
113+
@swagger_auto_schema(
114+
responses={status.HTTP_200_OK: DeploySerializer()},
115+
tags=["deploys"],
116+
)
117+
def partial_update(self, request, *args, **kwargs):
118+
return super().partial_update(request, *args, **kwargs)
119+
120+
@swagger_auto_schema(
121+
responses={
122+
status.HTTP_204_NO_CONTENT: openapi.Response("No Content"),
123+
},
124+
tags=["deploys"],
125+
)
126+
def destroy(self, request, *args, **kwargs):
127+
return super().destroy(request, *args, **kwargs)

‎estela-api/api/views/job.py‎

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,3 @@
1-
from datetime import date, timedelta
21
from django.shortcuts import get_object_or_404
32
from django_filters.rest_framework import DjangoFilterBackend
43
from drf_yasg.utils import swagger_auto_schema
@@ -80,6 +79,7 @@ def get_queryset(self):
8079
description="Job tag.",
8180
),
8281
],
82+
tags=["spider-jobs"],
8383
)
8484
def list(self, *args, **kwargs):
8585
return super(SpiderJobViewSet, self).list(*args, **kwargs)
@@ -95,6 +95,7 @@ def list(self, *args, **kwargs):
9595
],
9696
request_body=SpiderJobCreateSerializer,
9797
responses={status.HTTP_201_CREATED: SpiderJobCreateSerializer()},
98+
tags=["spider-jobs"],
9899
)
99100
def create(self, request, *args, **kwargs):
100101
spider = get_object_or_404(Spider, sid=self.kwargs["sid"], deleted=False)
@@ -146,6 +147,7 @@ def create(self, request, *args, **kwargs):
146147
@swagger_auto_schema(
147148
request_body=SpiderJobUpdateSerializer,
148149
responses={status.HTTP_200_OK: SpiderJobUpdateSerializer()},
150+
tags=["spider-jobs"],
149151
)
150152
def update(self, request, *args, **kwargs):
151153
partial = kwargs.pop("partial", False)
@@ -161,3 +163,17 @@ def update(self, request, *args, **kwargs):
161163

162164
headers = self.get_success_headers(serializer.data)
163165
return Response(serializer.data, status=status.HTTP_200_OK, headers=headers)
166+
167+
@swagger_auto_schema(
168+
responses={status.HTTP_200_OK: SpiderJobSerializer()},
169+
tags=["spider-jobs"],
170+
)
171+
def retrieve(self, request, *args, **kwargs):
172+
return super().retrieve(request, *args, **kwargs)
173+
174+
@swagger_auto_schema(
175+
responses={status.HTTP_200_OK: SpiderJobSerializer()},
176+
tags=["spider-jobs"],
177+
)
178+
def partial_update(self, request, *args, **kwargs):
179+
return super().partial_update(request, *args, **kwargs)

‎estela-api/api/views/job_data.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,7 @@ def get_paginated_link(self, page_number):
8484
required=False,
8585
),
8686
],
87+
tags=["spider-jobs"],
8788
)
8889
def list(self, request, *args, **kwargs):
8990
page, data_type, page_size = self.get_parameters(request)
@@ -161,6 +162,7 @@ def list(self, request, *args, **kwargs):
161162
required=True,
162163
),
163164
],
165+
tags=["spider-jobs"],
164166
)
165167
@action(methods=["POST"], detail=False)
166168
def delete(self, request, *args, **kwargs):

‎estela-api/api/views/project.py‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -74,6 +74,7 @@ def perform_create(self, serializer):
7474
@swagger_auto_schema(
7575
request_body=ProjectUpdateSerializer,
7676
responses={status.HTTP_200_OK: ProjectUpdateSerializer()},
77+
tags=["projects"],
7778
)
7879
def update(self, request, *args, **kwargs):
7980
partial = kwargs.pop("partial", False)
@@ -137,6 +138,7 @@ def update(self, request, *args, **kwargs):
137138

138139
@swagger_auto_schema(
139140
responses={status.HTTP_204_NO_CONTENT: "Project deleted"},
141+
tags=["projects"],
140142
)
141143
def destroy(self, request, *args, **kwargs):
142144
instance = self.get_object()
@@ -166,6 +168,7 @@ def perform_destroy(self, instance):
166168
),
167169
],
168170
responses={status.HTTP_200_OK: ProjectJobSerializer()},
171+
tags=["projects"],
169172
)
170173
@action(methods=["GET"], detail=True)
171174
def jobs(self, request, *args, **kwargs):
@@ -205,6 +208,7 @@ def jobs(self, request, *args, **kwargs):
205208
),
206209
],
207210
responses={status.HTTP_200_OK: ProjectCronJobSerializer()},
211+
tags=["projects"],
208212
)
209213
@action(methods=["GET"], detail=True)
210214
def cronjobs(self, request, *args, **kwargs):
@@ -227,6 +231,7 @@ def cronjobs(self, request, *args, **kwargs):
227231
@swagger_auto_schema(
228232
methods=["GET"],
229233
responses={status.HTTP_200_OK: ProjectUsageSerializer()},
234+
tags=["projects"],
230235
)
231236
@action(methods=["GET"], detail=True)
232237
def current_usage(self, request, *args, **kwargs):
@@ -258,6 +263,7 @@ def current_usage(self, request, *args, **kwargs):
258263
),
259264
],
260265
responses={status.HTTP_200_OK: UsageRecordSerializer(many=True)},
266+
tags=["projects"],
261267
)
262268
@action(methods=["GET"], detail=True)
263269
def usage(self, request, *args, **kwargs):
@@ -276,3 +282,30 @@ def usage(self, request, *args, **kwargs):
276282
serializer.data,
277283
status=status.HTTP_200_OK,
278284
)
285+
286+
@swagger_auto_schema(
287+
tags=["projects"],
288+
)
289+
def list(self, request, *args, **kwargs):
290+
return super().list(request, *args, **kwargs)
291+
292+
@swagger_auto_schema(
293+
responses={status.HTTP_200_OK: ProjectSerializer()},
294+
tags=["projects"],
295+
)
296+
def retrieve(self, request, *args, **kwargs):
297+
return super().retrieve(request, *args, **kwargs)
298+
299+
@swagger_auto_schema(
300+
responses={status.HTTP_201_CREATED: ProjectSerializer()},
301+
tags=["projects"],
302+
)
303+
def create(self, request, *args, **kwargs):
304+
return super().create(request, *args, **kwargs)
305+
306+
@swagger_auto_schema(
307+
responses={status.HTTP_200_OK: ProjectSerializer()},
308+
tags=["projects"],
309+
)
310+
def partial_update(self, request, *args, **kwargs):
311+
return super().partial_update(request, *args, **kwargs)

0 commit comments

Comments
 (0)