Update REST API documentation (#4391)

README.md

@@ -124,6 +124,10 @@ Prebuilt docker images for CVAT releases are available on Docker Hub:
 - [cvat_server](https://hub.docker.com/r/openvino/cvat_server)
 - [cvat_ui](https://hub.docker.com/r/openvino/cvat_ui)
 
+## REST API
+The current REST API version is `2.0-alpha`. We focus on its improvement and therefore
+REST API may be changed in the next release.
+
 ## LICENSE
 
 Code released under the [MIT License](https://opensource.org/licenses/MIT).

cvat/apps/iam/views.py

@@ -79,6 +79,7 @@ class ContextMiddleware:
         return self.get_response(request)
 
 
+@extend_schema(tags=['auth'])
 @extend_schema_view(post=extend_schema(
     summary='This method signs URL for access to the server',
     description='Signed URL contains a token which authenticates a user on the server.'
@@ -89,7 +90,7 @@ class ContextMiddleware:
             'url': serializers.CharField(),
         }
     ),
-    responses={'200': OpenApiResponse(response=OpenApiTypes.STR, description='text URL')}, tags=['auth'], versions=['2.0']))
+    responses={'200': OpenApiResponse(response=OpenApiTypes.STR, description='text URL')}))
 class SigningView(views.APIView):
 
     def post(self, request):

cvat/apps/lambda_manager/views.py

@@ -630,14 +630,16 @@ def return_response(success_code=status.HTTP_200_OK):
         return func_wrapper
     return wrap_response
 
-@extend_schema_view(retrieve=extend_schema(
+@extend_schema(tags=['lambda'])
+@extend_schema_view(
+    retrieve=extend_schema(
         summary='Method returns the information about the function',
         responses={
             '200': OpenApiResponse(response=OpenApiTypes.OBJECT, description='Information about the function'),
-    },
-    tags=['lambda'], versions=['2.0']))
-@extend_schema_view(list=extend_schema(
-    summary='Method returns a list of functions', tags=['lambda'], versions=['2.0']))
+        }),
+    list=extend_schema(
+        summary='Method returns a list of functions')
+)
 class FunctionViewSet(viewsets.ViewSet):
     lookup_value_regex = '[a-zA-Z0-9_.-]+'
     lookup_field = 'func_id'
@@ -672,21 +674,23 @@ class FunctionViewSet(viewsets.ViewSet):
 
         return lambda_func.invoke(db_task, request.data)
 
-@extend_schema_view(retrieve=extend_schema(
+@extend_schema(tags=['lambda'])
+@extend_schema_view(
+    retrieve=extend_schema(
         summary='Method returns the status of the request',
         parameters=[
             # specify correct type
             OpenApiParameter('id', location=OpenApiParameter.PATH, type=OpenApiTypes.INT,
                 description='Request id'),
-    ],
-    tags=['lambda'], versions=['2.0']))
-@extend_schema_view(list=extend_schema(
-    summary='Method returns a list of requests', tags=['lambda'], versions=['2.0']))
-#TODO
-@extend_schema_view(create=extend_schema(
-    summary='Method calls the function', tags=['lambda'], versions=['2.0']))
-@extend_schema_view(delete=extend_schema(
-    summary='Method cancels the request', tags=['lambda'], versions=['2.0']))
+        ]),
+    list=extend_schema(
+        summary='Method returns a list of requests'),
+    #TODO
+    create=extend_schema(
+        summary='Method calls the function'),
+    delete=extend_schema(
+        summary='Method cancels the request')
+)
 class RequestViewSet(viewsets.ViewSet):
     iam_organization_field = None
     serializer_class = None

cvat/apps/organizations/views.py

-# Copyright (C) 2021 Intel Corporation
+# Copyright (C) 2021-2022 Intel Corporation
 #
 # SPDX-License-Identifier: MIT
 
@@ -17,36 +17,39 @@ from .serializers import (
     MembershipReadSerializer, MembershipWriteSerializer,
     OrganizationReadSerializer, OrganizationWriteSerializer)
 
-@extend_schema_view(retrieve=extend_schema(
+@extend_schema(tags=['organizations'])
+@extend_schema_view(
+    retrieve=extend_schema(
         summary='Method returns details of an organization',
         responses={
             '200': OrganizationReadSerializer,
-    }, tags=['organizations'], versions=['2.0']))
-@extend_schema_view(list=extend_schema(
+        }),
+    list=extend_schema(
         summary='Method returns a paginated list of organizatins according to query parameters',
         responses={
             '200': OrganizationReadSerializer(many=True),
-    }, tags=['organizations'], versions=['2.0']))
-@extend_schema_view(update=extend_schema(
+        }),
+    update=extend_schema(
         summary='Method updates an organization by id',
         responses={
             '200': OrganizationWriteSerializer,
-    }, tags=['organizations'], versions=['2.0']))
-@extend_schema_view(partial_update=extend_schema(
+        }),
+    partial_update=extend_schema(
         summary='Methods does a partial update of chosen fields in an organization',
         responses={
             '200': OrganizationWriteSerializer,
-   }, tags=['organizations'], versions=['2.0']))
-@extend_schema_view(create=extend_schema(
+        }),
+    create=extend_schema(
         summary='Method creates an organization',
         responses={
             '201': OrganizationWriteSerializer,
-    }, tags=['organizations'], versions=['2.0']))
-@extend_schema_view(destroy=extend_schema(
+        }),
+    destroy=extend_schema(
         summary='Method deletes an organization',
         responses={
             '204': OpenApiResponse(description='The organization has been deleted'),
-    }, tags=['organizations'], versions=['2.0']))
+        })
+)
 class OrganizationViewSet(viewsets.ModelViewSet):
     queryset = Organization.objects.all()
     search_fields = ('name', 'owner')
@@ -78,31 +81,35 @@ class OrganizationViewSet(viewsets.ModelViewSet):
     class Meta:
         model = Membership
         fields = ("user", )
-@extend_schema_view(retrieve=extend_schema(
+
+@extend_schema(tags=['memberships'])
+@extend_schema_view(
+    retrieve=extend_schema(
         summary='Method returns details of a membership',
         responses={
             '200': MembershipReadSerializer,
-    }, tags=['memberships'], versions=['2.0']))
-@extend_schema_view(list=extend_schema(
+        }),
+    list=extend_schema(
         summary='Method returns a paginated list of memberships according to query parameters',
         responses={
             '200': MembershipReadSerializer(many=True),
-    }, tags=['memberships'], versions=['2.0']))
-@extend_schema_view(update=extend_schema(
+        }),
+    update=extend_schema(
         summary='Method updates a membership by id',
         responses={
             '200': MembershipWriteSerializer,
-    }, tags=['memberships'], versions=['2.0']))
-@extend_schema_view(partial_update=extend_schema(
+        }),
+    partial_update=extend_schema(
         summary='Methods does a partial update of chosen fields in a membership',
         responses={
             '200': MembershipWriteSerializer,
-   }, tags=['memberships'], versions=['2.0']))
-@extend_schema_view(destroy=extend_schema(
+        }),
+    destroy=extend_schema(
         summary='Method deletes a membership',
         responses={
             '204': OpenApiResponse(description='The membership has been deleted'),
-    }, tags=['memberships'], versions=['2.0']))
+        })
+)
 class MembershipViewSet(mixins.RetrieveModelMixin, mixins.DestroyModelMixin,
     mixins.ListModelMixin, mixins.UpdateModelMixin, viewsets.GenericViewSet):
     queryset = Membership.objects.all()
@@ -125,37 +132,39 @@ class MembershipViewSet(mixins.RetrieveModelMixin, mixins.DestroyModelMixin,
         permission = MembershipPermission.create_scope_list(self.request)
         return permission.filter(queryset)
 
-# TODO
-@extend_schema_view(retrieve=extend_schema(
+@extend_schema(tags=['invitations'])
+@extend_schema_view(
+    retrieve=extend_schema(
         summary='Method returns details of an invitation',
         responses={
             '200': InvitationReadSerializer,
-    }, tags=['invitations'], versions=['2.0']))
-@extend_schema_view(list=extend_schema(
+        }),
+    list=extend_schema(
         summary='Method returns a paginated list of invitations according to query parameters',
         responses={
             '200': InvitationReadSerializer(many=True),
-    }, tags=['invitations'], versions=['2.0']))
-@extend_schema_view(update=extend_schema(
+        }),
+    update=extend_schema(
         summary='Method updates an invitation by id',
         responses={
             '200': InvitationWriteSerializer,
-    }, tags=['invitations'], versions=['2.0']))
-@extend_schema_view(partial_update=extend_schema(
+        }),
+    partial_update=extend_schema(
         summary='Methods does a partial update of chosen fields in an invitation',
         responses={
             '200': InvitationWriteSerializer,
-   }, tags=['invitations'], versions=['2.0']))
-@extend_schema_view(create=extend_schema(
+        }),
+    create=extend_schema(
         summary='Method creates an invitation',
         responses={
             '201': InvitationWriteSerializer,
-    }, tags=['invitations'], versions=['2.0']))
-@extend_schema_view(destroy=extend_schema(
+        }),
+    destroy=extend_schema(
         summary='Method deletes an invitation',
         responses={
             '204': OpenApiResponse(description='The invitation has been deleted'),
-    }, tags=['invitations'], versions=['2.0']))
+        })
+)
 class InvitationViewSet(viewsets.ModelViewSet):
     queryset = Invitation.objects.all()
     http_method_names = ['get', 'post', 'patch', 'delete', 'head', 'options']

cvat/apps/restrictions/views.py

@@ -13,6 +13,7 @@ from drf_spectacular.utils import OpenApiResponse, extend_schema
 
 from cvat.apps.restrictions.serializers import UserAgreementSerializer
 
+@extend_schema(tags=['restrictions'])
 class RestrictionsViewSet(viewsets.ViewSet):
     serializer_class = None
     permission_classes = [AllowAny]
@@ -26,8 +27,7 @@ class RestrictionsViewSet(viewsets.ViewSet):
 
     @staticmethod
     @extend_schema(summary='Method provides user agreements that the user must accept to register',
-                  responses={'200': UserAgreementSerializer},
-                  tags=['restrictions'], versions=['2.0'])
+                  responses={'200': UserAgreementSerializer})
     @action(detail=False, methods=['GET'], serializer_class=UserAgreementSerializer, url_path='user-agreements')
     def user_agreements(request):
         user_agreements = settings.RESTRICTIONS['user_agreements']
@@ -37,8 +37,7 @@ class RestrictionsViewSet(viewsets.ViewSet):
 
     @staticmethod
     @extend_schema(summary='Method provides CVAT terms of use',
-                responses={'200': OpenApiResponse(description='CVAT terms of use')},
-                tags=['restrictions'], versions=['2.0'])
+                responses={'200': OpenApiResponse(description='CVAT terms of use')})
     @action(detail=False, methods=['GET'], renderer_classes=(TemplateHTMLRenderer,),
         url_path='terms-of-use')
     def terms_of_use(request):

cvat/settings/base.py

@@ -501,7 +501,7 @@ SPECTACULAR_SETTINGS = {
     # Statically set schema version. May also be an empty string. When used together with
     # view versioning, will become '0.0.0 (v2)' for 'v2' versioned requests.
     # Set VERSION to None if only the request version should be rendered.
-    'VERSION': None,
+    'VERSION': 'alpha',
     'CONTACT': {
         'name': 'Nikita Manovich',
         'url': 'https://github.com/nmanovic',