Streamline API endpoint summaries (#7685)

The current summaries are much too verbose. This makes it hard to find the endpoint you're looking for in the API docs, because it takes longer to read & understand each summary. Rewrite them to be more brief. Move any details that are too long to keep, but too important to omit, to the description.
cvat-ai · Mar 28, 2024 · 85f5376 · 85f5376
1 parent 6d2e909
commit 85f5376
Show file tree

Hide file tree

Showing 7 changed files with 315 additions and 303 deletions.
diff --git a/cvat/apps/analytics_report/views.py b/cvat/apps/analytics_report/views.py
@@ -29,7 +29,7 @@ def get_queryset(self):
 
     @extend_schema(
         operation_id="analytics_create_report",
-        summary="Creates a analytics report asynchronously and allows to check request status",
+        summary="Create an analytics report",
         parameters=[
             OpenApiParameter(
                 "rq_id",
@@ -144,7 +144,7 @@ def create(self, request, *args, **kwargs):
                 return Response(serializer.data, status=status.HTTP_201_CREATED)
 
     @extend_schema(
-        summary="Method returns analytics report",
+        summary="Get an analytics report",
         methods=["GET"],
         operation_id="analytics_get_reports",
         description="Receive analytics report",

diff --git a/cvat/apps/engine/views.py b/cvat/apps/engine/views.py
diff --git a/cvat/apps/events/views.py b/cvat/apps/events/views.py
@@ -19,7 +19,7 @@
 class EventsViewSet(viewsets.ViewSet):
     serializer_class = None
 
-    @extend_schema(summary='Method saves logs from a client on the server',
+    @extend_schema(summary='Log client events',
         methods=['POST'],
         description='Sends logs to the Clickhouse if it is connected',
         parameters=ORGANIZATION_OPEN_API_PARAMETERS,
@@ -37,9 +37,9 @@ def create(self, request):
 
         return Response(serializer.data, status=status.HTTP_201_CREATED)
 
-    @extend_schema(summary='Method returns csv log file ',
+    @extend_schema(summary='Get an event log',
         methods=['GET'],
-        description='Receive logs from the server',
+        description='The log is returned in the CSV format.',
         parameters=[
             OpenApiParameter('org_id', location=OpenApiParameter.QUERY, type=OpenApiTypes.INT, required=False,
                 description="Filter events by organization ID"),

diff --git a/cvat/apps/organizations/views.py b/cvat/apps/organizations/views.py
@@ -31,29 +31,29 @@
 @extend_schema(tags=['organizations'])
 @extend_schema_view(
     retrieve=extend_schema(
-        summary='Method returns details of an organization',
+        summary='Get organization details',
         responses={
             '200': OrganizationReadSerializer,
         }),
     list=extend_schema(
-        summary='Method returns a paginated list of organizations',
+        summary='List organizations',
         responses={
             '200': OrganizationReadSerializer(many=True),
         }),
     partial_update=extend_schema(
-        summary='Methods does a partial update of chosen fields in an organization',
+        summary='Update an organization',
         request=OrganizationWriteSerializer(partial=True),
         responses={
             '200': OrganizationReadSerializer, # check OrganizationWriteSerializer.to_representation
         }),
     create=extend_schema(
-        summary='Method creates an organization',
+        summary='Create an organization',
         request=OrganizationWriteSerializer,
         responses={
             '201': OrganizationReadSerializer, # check OrganizationWriteSerializer.to_representation
         }),
     destroy=extend_schema(
-        summary='Method deletes an organization',
+        summary='Delete an organization',
         responses={
             '204': OpenApiResponse(description='The organization has been deleted'),
         })
@@ -100,23 +100,23 @@ class Meta:
 @extend_schema(tags=['memberships'])
 @extend_schema_view(
     retrieve=extend_schema(
-        summary='Method returns details of a membership',
+        summary='Get membership details',
         responses={
             '200': MembershipReadSerializer,
         }),
     list=extend_schema(
-        summary='Method returns a paginated list of memberships',
+        summary='List memberships',
         responses={
             '200': MembershipReadSerializer(many=True),
         }),
     partial_update=extend_schema(
-        summary='Methods does a partial update of chosen fields in a membership',
+        summary='Update a membership',
         request=MembershipWriteSerializer(partial=True),
         responses={
             '200': MembershipReadSerializer, # check MembershipWriteSerializer.to_representation
         }),
     destroy=extend_schema(
-        summary='Method deletes a membership',
+        summary='Delete a membership',
         responses={
             '204': OpenApiResponse(description='The membership has been deleted'),
         })
@@ -151,51 +151,51 @@ def get_queryset(self):
 @extend_schema(tags=['invitations'])
 @extend_schema_view(
     retrieve=extend_schema(
-        summary='Method returns details of an invitation',
+        summary='Get invitation details',
         responses={
             '200': InvitationReadSerializer,
         }),
     list=extend_schema(
-        summary='Method returns a paginated list of invitations',
+        summary='List invitations',
         responses={
             '200': InvitationReadSerializer(many=True),
         }),
     partial_update=extend_schema(
-        summary='Methods does a partial update of chosen fields in an invitation',
+        summary='Update an invitation',
         request=InvitationWriteSerializer(partial=True),
         responses={
             '200': InvitationReadSerializer, # check InvitationWriteSerializer.to_representation
         }),
     create=extend_schema(
-        summary='Method creates an invitation',
+        summary='Create an invitation',
         request=InvitationWriteSerializer,
         parameters=ORGANIZATION_OPEN_API_PARAMETERS,
         responses={
             '201': InvitationReadSerializer, # check InvitationWriteSerializer.to_representation
         }),
     destroy=extend_schema(
-        summary='Method deletes an invitation',
+        summary='Delete an invitation',
         responses={
             '204': OpenApiResponse(description='The invitation has been deleted'),
         }),
     accept=extend_schema(
         operation_id='invitations_accept',
         request=None,
-        summary='Method registers user and accepts invitation to organization',
+        summary='Accept an invitation',
         responses={
             '200': OpenApiResponse(response=AcceptInvitationReadSerializer, description='The invitation is accepted'),
             '400': OpenApiResponse(description='The invitation is expired or already accepted'),
         }),
     decline=extend_schema(
         operation_id='invitations_decline',
         request=None,
-        summary='Method declines the invitation to organization',
+        summary='Decline an invitation',
         responses={
             '204': OpenApiResponse(description='The invitation has been declined'),
         }),
     resend=extend_schema(
         operation_id='invitations_resend',
-        summary='Method resends the invitation to organization',
+        summary='Resend an invitation',
         request=None,
         responses={
             '204': OpenApiResponse(description='Invitation has been sent'),

diff --git a/cvat/apps/quality_control/views.py b/cvat/apps/quality_control/views.py
@@ -45,7 +45,7 @@
 @extend_schema(tags=["quality"])
 @extend_schema_view(
     list=extend_schema(
-        summary="Method returns a paginated list of annotation conflicts",
+        summary="List annotation conflicts in a quality report",
         parameters=[
             # These filters are implemented differently from others
             OpenApiParameter(
@@ -126,13 +126,13 @@ def get_queryset(self):
 @extend_schema_view(
     retrieve=extend_schema(
         operation_id="quality_retrieve_report",  # the default produces the plural
-        summary="Method returns details of a quality report",
+        summary="Get quality report details",
         responses={
             "200": QualityReportSerializer,
         },
     ),
     list=extend_schema(
-        summary="Method returns a paginated list of quality reports",
+        summary="List quality reports",
         parameters=[
             # These filters are implemented differently from others
             OpenApiParameter(
@@ -221,7 +221,7 @@ def get_queryset(self):
 
     @extend_schema(
         operation_id="quality_create_report",
-        summary="Creates a quality report asynchronously and allows to check request status",
+        summary="Create a quality report",
         parameters=[
             OpenApiParameter(
                 CREATE_REPORT_RQ_ID_PARAMETER,
@@ -320,7 +320,7 @@ def create(self, request, *args, **kwargs):
 
     @extend_schema(
         operation_id="quality_retrieve_report_data",
-        summary="Retrieve full contents of the report in JSON format",
+        summary="Get quality report contents",
         responses={"200": OpenApiTypes.OBJECT},
     )
     @action(detail=True, methods=["GET"], url_path="data", serializer_class=None)
@@ -333,13 +333,13 @@ def data(self, request, pk):
 @extend_schema(tags=["quality"])
 @extend_schema_view(
     list=extend_schema(
-        summary="Method returns a paginated list of quality settings instances",
+        summary="List quality settings instances",
         responses={
             "200": QualitySettingsSerializer(many=True),
         },
     ),
     retrieve=extend_schema(
-        summary="Method returns details of the quality settings instance",
+        summary="Get quality settings instance details",
         parameters=[
             OpenApiParameter(
                 "id",
@@ -353,7 +353,7 @@ def data(self, request, pk):
         },
     ),
     partial_update=extend_schema(
-        summary="Methods does a partial update of chosen fields in the quality settings instance",
+        summary="Update a quality settings instance",
         parameters=[
             OpenApiParameter(
                 "id",

diff --git a/cvat/apps/webhooks/views.py b/cvat/apps/webhooks/views.py
@@ -24,37 +24,37 @@
 @extend_schema(tags=["webhooks"])
 @extend_schema_view(
     retrieve=extend_schema(
-        summary="Method returns details of a webhook",
+        summary="Get webhook details",
         responses={"200": WebhookReadSerializer},
     ),
     list=extend_schema(
-        summary="Method returns a paginated list of webhook according to query parameters",
+        summary="List webhooks",
         responses={"200": WebhookReadSerializer(many=True)},
     ),
     update=extend_schema(
-        summary="Method updates a webhook by id",
+        summary="Replace a webhook",
         request=WebhookWriteSerializer,
         responses={
             "200": WebhookReadSerializer
         },  # check WebhookWriteSerializer.to_representation
     ),
     partial_update=extend_schema(
-        summary="Methods does a partial update of chosen fields in a webhook",
+        summary="Update a webhook",
         request=WebhookWriteSerializer,
         responses={
             "200": WebhookReadSerializer
         },  # check WebhookWriteSerializer.to_representation
     ),
     create=extend_schema(
         request=WebhookWriteSerializer,
-        summary="Method creates a webhook",
+        summary="Create a webhook",
         parameters=ORGANIZATION_OPEN_API_PARAMETERS,
         responses={
             "201": WebhookReadSerializer
         },  # check WebhookWriteSerializer.to_representation
     ),
     destroy=extend_schema(
-        summary="Method deletes a webhook",
+        summary="Delete a webhook",
         responses={"204": OpenApiResponse(description="The webhook has been deleted")},
     ),
 )
@@ -97,7 +97,7 @@ def perform_create(self, serializer):
         )
 
     @extend_schema(
-        summary="Method return a list of available webhook events",
+        summary="List available webhook events",
         parameters=[
             OpenApiParameter(
                 "type",
@@ -128,7 +128,7 @@ def events(self, request):
         return Response(EventsSerializer().to_representation(events))
 
     @extend_schema(
-        summary="Method return a list of deliveries for a specific webhook",
+        summary="List deliveries for a webhook",
         responses=WebhookDeliveryReadSerializer(
             many=True
         ),  # Duplicate to still get 'list' op. name
@@ -144,7 +144,7 @@ def deliveries(self, request, pk):
         )  # from @action
 
     @extend_schema(
-        summary="Method return a specific delivery for a specific webhook",
+        summary="Get details of a webhook delivery",
         responses={"200": WebhookDeliveryReadSerializer},
     )
     @action(
@@ -162,7 +162,7 @@ def retrieve_delivery(self, request, pk, delivery_id):
         return Response(serializer.data)
 
     @extend_schema(
-        summary="Method redeliver a specific webhook delivery",
+        summary="Redeliver a webhook delivery",
         request=None,
         responses={200: None},
     )
@@ -178,7 +178,7 @@ def redelivery(self, request, pk, delivery_id):
         return Response({}, status=status.HTTP_200_OK)
 
     @extend_schema(
-        summary="Method send ping webhook",
+        summary="Send a ping webhook",
         request=None,
         responses={"200": WebhookDeliveryReadSerializer},
     )