From 85f5376b0e4b19eaccb60e598e07a8502cfc8d5d Mon Sep 17 00:00:00 2001 From: Roman Donchenko Date: Thu, 28 Mar 2024 22:04:26 +0200 Subject: [PATCH] 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/apps/analytics_report/views.py | 4 +- cvat/apps/engine/views.py | 219 ++++++++++--------- cvat/apps/events/views.py | 6 +- cvat/apps/organizations/views.py | 34 +-- cvat/apps/quality_control/views.py | 16 +- cvat/apps/webhooks/views.py | 22 +- cvat/schema.yml | 317 ++++++++++++++-------------- 7 files changed, 315 insertions(+), 303 deletions(-) diff --git a/cvat/apps/analytics_report/views.py b/cvat/apps/analytics_report/views.py index 4317915a0dbc..4723a705cf27 100644 --- 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 index bf65fdb13408..53867cbe8907 100644 --- a/cvat/apps/engine/views.py +++ b/cvat/apps/engine/views.py @@ -103,7 +103,7 @@ def get_serializer(self, *args, **kwargs): pass @staticmethod - @extend_schema(summary='Method provides basic CVAT information', + @extend_schema(summary='Get basic CVAT information', responses={ '200': AboutSerializer, }) @@ -129,7 +129,7 @@ def about(request): @staticmethod @extend_schema( - summary='Returns all files and folders that are on the server along specified path', + summary='List files/directories in the mounted share', parameters=[ OpenApiParameter('directory', description='Directory to browse', location=OpenApiParameter.QUERY, type=OpenApiTypes.STR), @@ -180,7 +180,7 @@ def share(request): @staticmethod @extend_schema( - summary='Method provides the list of supported annotations formats', + summary='Get supported annotation formats', responses={ '200': DatasetFormatsSerializer, }) @@ -191,7 +191,7 @@ def annotation_formats(request): @staticmethod @extend_schema( - summary='Method provides allowed plugins', + summary='Get enabled plugins', responses={ '200': PluginsSerializer, }) @@ -208,29 +208,29 @@ def plugins(request): @extend_schema(tags=['projects']) @extend_schema_view( list=extend_schema( - summary='Returns a paginated list of projects', + summary='List projects', responses={ '200': ProjectReadSerializer(many=True), }), create=extend_schema( - summary='Method creates a new project', + summary='Create a project', request=ProjectWriteSerializer, parameters=ORGANIZATION_OPEN_API_PARAMETERS, responses={ '201': ProjectReadSerializer, # check ProjectWriteSerializer.to_representation }), retrieve=extend_schema( - summary='Method returns details of a specific project', + summary='Get project details', responses={ '200': ProjectReadSerializer, }), destroy=extend_schema( - summary='Method deletes a specific project', + summary='Delete a project', responses={ '204': OpenApiResponse(description='The project has been deleted'), }), partial_update=extend_schema( - summary='Methods does a partial update of chosen fields in a project', + summary='Update a project', request=ProjectWriteSerializer(partial=True), responses={ '200': ProjectReadSerializer, # check ProjectWriteSerializer.to_representation @@ -279,7 +279,7 @@ def perform_create(self, serializer, **kwargs): # Required for the extra summary information added in the queryset serializer.instance = self.get_queryset().get(pk=serializer.instance.pk) - @extend_schema(methods=['GET'], summary='Export project as a dataset in a specific format', + @extend_schema(methods=['GET'], summary='Export a project as a dataset / Check dataset import status', description=textwrap.dedent(""" To check the status of the process of importing a project dataset from a file: @@ -314,7 +314,7 @@ def perform_create(self, serializer, **kwargs): '405': OpenApiResponse(description='Format is not available'), }) @extend_schema(methods=['POST'], - summary='Import dataset in specific format as a project or check status of dataset import process', + summary='Import a dataset into a project', description=textwrap.dedent(""" The request POST /api/projects/id/dataset will initiate file upload and will create the rq job on the server in which the process of dataset import from a file @@ -448,7 +448,7 @@ def upload_finished(self, request): return Response(data='Unknown upload was finished', status=status.HTTP_400_BAD_REQUEST) - @extend_schema(summary='Method allows to download project annotations', + @extend_schema(summary='Get project annotations', parameters=[ OpenApiParameter('format', description='Desired output format name\n' 'You can get the list of supported formats at:\n/server/annotation/formats', @@ -489,7 +489,7 @@ def annotations(self, request, pk): get_data=dm.task.get_job_data, ) - @extend_schema(summary='Methods creates a backup copy of a project', + @extend_schema(summary='Back up a project', parameters=[ OpenApiParameter('action', location=OpenApiParameter.QUERY, description='Used to start downloading process after backup file had been created', @@ -514,7 +514,7 @@ def annotations(self, request, pk): def export_backup(self, request, pk=None): return self.serialize(request, backup.export) - @extend_schema(methods=['POST'], summary='Methods create a project from a backup', + @extend_schema(methods=['POST'], summary='Recreate a project from a backup', description=textwrap.dedent(""" The backup import process is as follows: @@ -562,7 +562,7 @@ def import_backup(self, request, pk=None): def append_backup_chunk(self, request, file_id): return self.append_tus_chunk(request, file_id) - @extend_schema(summary='Method returns a preview image for the project', + @extend_schema(summary='Get a preview image for a project', responses={ '200': OpenApiResponse(description='Project image preview'), '404': OpenApiResponse(description='Project image preview not found'), @@ -728,29 +728,34 @@ def __call__(self, request, start, stop, db_data): @extend_schema(tags=['tasks']) @extend_schema_view( list=extend_schema( - summary='Returns a paginated list of tasks', + summary='List tasks', responses={ '200': TaskReadSerializer(many=True), }), create=extend_schema( - summary='Method creates a new task in a database without any attached images and videos', + summary='Create a task', + description=textwrap.dedent("""\ + The new task will not have any attached images or videos. + To attach them, use the /api/tasks//data endpoint. + """), request=TaskWriteSerializer, parameters=ORGANIZATION_OPEN_API_PARAMETERS, responses={ '201': TaskReadSerializer, # check TaskWriteSerializer.to_representation }), retrieve=extend_schema( - summary='Method returns details of a specific task', + summary='Get task details', responses={ '200': TaskReadSerializer }), destroy=extend_schema( - summary='Method deletes a specific task, all attached jobs, annotations, and data', + summary='Delete a task', + description='All attached jobs, annotations and data will be deleted as well.', responses={ '204': OpenApiResponse(description='The task has been deleted'), }), partial_update=extend_schema( - summary='Methods does a partial update of chosen fields in a task', + summary='Update a task', request=TaskWriteSerializer(partial=True), responses={ '200': TaskReadSerializer, # check TaskWriteSerializer.to_representation @@ -807,7 +812,7 @@ def get_queryset(self): return queryset - @extend_schema(summary='Method recreates a task from an attached task backup file', + @extend_schema(summary='Recreate a task from a backup', description=textwrap.dedent(""" The backup import process is as follows: @@ -852,7 +857,7 @@ def import_backup(self, request, pk=None): def append_backup_chunk(self, request, file_id): return self.append_tus_chunk(request, file_id) - @extend_schema(summary='Method backup a specified task', + @extend_schema(summary='Back up a task', parameters=[ OpenApiParameter('action', location=OpenApiParameter.QUERY, description='Used to start downloading process after backup file had been created', @@ -1102,9 +1107,9 @@ def _handle_upload_backup(request): assert _UPLOAD_FILE_ORDER_FIELD in DataSerializer().fields @extend_schema(methods=['POST'], - summary="Method permanently attaches data (images, video, etc.) to a task", + summary="Attach data to a task", description=textwrap.dedent("""\ - Allows to upload data to a task. + Allows to upload data (images, video, etc.) to a task. Supports the TUS open file uploading protocol (https://tus.io/). Supports the following protocols: @@ -1153,6 +1158,8 @@ def _handle_upload_backup(request): After all data is sent, the operation status can be retrieved via the /status endpoint. + + Once data is attached to a task, it cannot be detached or replaced. """.format_map( {'upload_file_order_field': _UPLOAD_FILE_ORDER_FIELD} )), @@ -1170,7 +1177,7 @@ def _handle_upload_backup(request): '202': OpenApiResponse(description=''), }) @extend_schema(methods=['GET'], - summary='Method returns data for a specific task', + summary='Get data of a task', parameters=[ OpenApiParameter('type', location=OpenApiParameter.QUERY, required=False, type=OpenApiTypes.STR, enum=['chunk', 'frame', 'context_image'], @@ -1224,7 +1231,7 @@ def append_data_chunk(self, request, pk, file_id): self._object = self.get_object() return self.append_tus_chunk(request, file_id) - @extend_schema(methods=['GET'], summary='Method allows to download task annotations', + @extend_schema(methods=['GET'], summary='Get task annotations', parameters=[ OpenApiParameter('format', location=OpenApiParameter.QUERY, type=OpenApiTypes.STR, required=False, description="Desired output format name\nYou can get the list of supported formats at:\n/server/annotation/formats"), @@ -1253,13 +1260,13 @@ def append_data_chunk(self, request, pk, file_id): '400': OpenApiResponse(description='Exporting without data is not allowed'), '405': OpenApiResponse(description='Format is not available'), }) - @extend_schema(methods=['PUT'], summary='Method allows to upload task annotations or edit existing annotations', + @extend_schema(methods=['PUT'], summary='Replace task annotations / Get annotation import status', description=textwrap.dedent(""" - To check the status of the process of uploading a task annotations from a file: + To check the status of an import request: - After initiating the annotations upload, you will receive an rq_id parameter. + After initiating the annotation import, you will receive an rq_id parameter. Make sure to include this parameter as a query parameter in your subsequent - PUT /api/tasks/id/annotations requests to track the status of the annotations upload. + PUT /api/tasks/id/annotations requests to track the status of the import. """), parameters=[ OpenApiParameter('format', location=OpenApiParameter.QUERY, type=OpenApiTypes.STR, required=False, @@ -1273,16 +1280,16 @@ def append_data_chunk(self, request, pk, file_id): resource_type_field_name=None ), responses={ - '201': OpenApiResponse(description='Uploading has finished'), - '202': OpenApiResponse(description='Uploading has been started'), + '201': OpenApiResponse(description='Import has finished'), + '202': OpenApiResponse(description='Import is in progress'), '405': OpenApiResponse(description='Format is not available'), }) @extend_schema(methods=['POST'], - summary="Method allows to initialize the process of upload task annotations from a local or a cloud storage file", + summary="Import annotations into a task", description=textwrap.dedent(""" - The request POST /api/tasks/id/annotations will initiate file upload and will create - the rq job on the server in which the process of annotations uploading from file - will be carried out. Please, use the PUT /api/tasks/id/annotations endpoint for checking status of the process. + The request POST /api/tasks/id/annotations will initiate the import and will create + the rq job on the server in which the import will be carried out. + Please, use the PUT /api/tasks/id/annotations endpoint for checking status of the process. """), parameters=[ OpenApiParameter('format', location=OpenApiParameter.QUERY, type=OpenApiTypes.STR, required=False, @@ -1308,7 +1315,7 @@ def append_data_chunk(self, request, pk, file_id): '202': OpenApiResponse(RqIdSerializer, description='Uploading has been started'), '405': OpenApiResponse(description='Format is not available'), }) - @extend_schema(methods=['PATCH'], summary='Method performs a partial update of annotations in a specific task', + @extend_schema(methods=['PATCH'], summary='Update task annotations', parameters=[ OpenApiParameter('action', location=OpenApiParameter.QUERY, required=True, type=OpenApiTypes.STR, enum=['create', 'update', 'delete']), @@ -1317,7 +1324,7 @@ def append_data_chunk(self, request, pk, file_id): responses={ '200': LabeledDataSerializer, }) - @extend_schema(methods=['DELETE'], summary='Method deletes all annotations for a specific task', + @extend_schema(methods=['DELETE'], summary='Delete task annotations', responses={ '204': OpenApiResponse(description='The annotation has been deleted'), }) @@ -1393,7 +1400,7 @@ def append_annotations_chunk(self, request, pk, file_id): return self.append_tus_chunk(request, file_id) @extend_schema( - summary='When task is being created the method returns information about a status of the creation process', + summary='Get the creation status of a task', responses={ '200': RqStatusSerializer, }) @@ -1432,11 +1439,11 @@ def _get_rq_response(queue, job_id): return response - @extend_schema(summary='Method provides a meta information about media files which are related with the task', + @extend_schema(methods=['GET'], summary='Get metainformation for media files in a task', responses={ '200': DataMetaReadSerializer, }) - @extend_schema(methods=['PATCH'], summary='Method performs an update of data meta fields (deleted frames)', + @extend_schema(methods=['PATCH'], summary='Update metainformation for media files in a task', request=DataMetaWriteSerializer, responses={ '200': DataMetaReadSerializer, @@ -1515,7 +1522,7 @@ def dataset_export(self, request, pk): return Response(data="Exporting a dataset from a task without data is not allowed", status=status.HTTP_400_BAD_REQUEST) - @extend_schema(summary='Method returns a preview image for the task', + @extend_schema(summary='Get a preview image for a task', responses={ '200': OpenApiResponse(description='Task image preview'), '404': OpenApiResponse(description='Task image preview not found'), @@ -1541,30 +1548,32 @@ def preview(self, request, pk): @extend_schema(tags=['jobs']) @extend_schema_view( create=extend_schema( - summary='Method creates a new job in the task', + summary='Create a job', request=JobWriteSerializer, responses={ '201': JobReadSerializer, # check JobWriteSerializer.to_representation }), retrieve=extend_schema( - summary='Method returns details of a job', + summary='Get job details', responses={ '200': JobReadSerializer, }), list=extend_schema( - summary='Method returns a paginated list of jobs', + summary='List jobs', responses={ '200': JobReadSerializer(many=True), }), partial_update=extend_schema( - summary='Methods does a partial update of chosen fields in a job', + summary='Update a job', request=JobWriteSerializer(partial=True), responses={ '200': JobReadSerializer, # check JobWriteSerializer.to_representation }), destroy=extend_schema( - summary='Method deletes a job and its related annotations', + summary='Delete a job', description=textwrap.dedent("""\ + Related annotations will be deleted as well. + Please note, that not every job can be removed. Currently, it is only available for Ground Truth jobs. """), @@ -1657,8 +1666,11 @@ def upload_finished(self, request): status=status.HTTP_400_BAD_REQUEST) @extend_schema(methods=['GET'], - summary="Method returns annotations for a specific job as a JSON document. " - "If format is specified, a zip archive is returned.", + summary="Get job annotations", + description=textwrap.dedent("""\ + If format is specified, a ZIP archive will be returned. Otherwise, + the annotations will be returned as a JSON document. + """), parameters=[ OpenApiParameter('format', location=OpenApiParameter.QUERY, description='Desired output format name\nYou can get the list of supported formats at:\n/server/annotation/formats', @@ -1688,11 +1700,11 @@ def upload_finished(self, request): '405': OpenApiResponse(description='Format is not available'), }) @extend_schema(methods=['POST'], - summary='Method allows to initialize the process of the job annotation upload from a local file or a cloud storage', + summary='Import annotations into a job', description=textwrap.dedent(""" - The request POST /api/jobs/id/annotations will initiate file upload and will create - the rq job on the server in which the process of annotations uploading from file - will be carried out. Please, use the PUT /api/jobs/id/annotations endpoint for checking status of the process. + The request POST /api/jobs/id/annotations will initiate the import and will create + the rq job on the server in which the import will be carried out. + Please, use the PUT /api/jobs/id/annotations endpoint for checking status of the process. """), parameters=[ OpenApiParameter('format', location=OpenApiParameter.QUERY, type=OpenApiTypes.STR, required=False, @@ -1715,14 +1727,13 @@ def upload_finished(self, request): '405': OpenApiResponse(description='Format is not available'), }) @extend_schema(methods=['PUT'], - summary='Method performs an update of all annotations in a specific job ' - 'or used for uploading annotations from a file', + summary='Replace job annotations / Get annotation import status', description=textwrap.dedent(""" - To check the status of the process of uploading a job annotations from a file: + To check the status of an import request: - After initiating the annotations upload, you will receive an rq_id parameter. + After initiating the annotation import, you will receive an rq_id parameter. Make sure to include this parameter as a query parameter in your subsequent - PUT /api/jobs/id/annotations requests to track the status of the annotations upload. + PUT /api/jobs/id/annotations requests to track the status of the import. """), parameters=[ OpenApiParameter('format', location=OpenApiParameter.QUERY, type=OpenApiTypes.STR, required=False, @@ -1746,11 +1757,11 @@ def upload_finished(self, request): resource_type_field_name=None ), responses={ - '201': OpenApiResponse(description='Uploading has finished'), - '202': OpenApiResponse(description='Uploading has been started'), + '201': OpenApiResponse(description='Import has finished'), + '202': OpenApiResponse(description='Import is in progress'), '405': OpenApiResponse(description='Format is not available'), }) - @extend_schema(methods=['PATCH'], summary='Method performs a partial update of annotations in a specific job', + @extend_schema(methods=['PATCH'], summary='Update job annotations', parameters=[ OpenApiParameter('action', location=OpenApiParameter.QUERY, type=OpenApiTypes.STR, required=True, enum=['create', 'update', 'delete']) @@ -1759,7 +1770,7 @@ def upload_finished(self, request): responses={ '200': OpenApiResponse(description='Annotations successfully uploaded'), }) - @extend_schema(methods=['DELETE'], summary='Method deletes all annotations for a specific job', + @extend_schema(methods=['DELETE'], summary='Delete job annotations', responses={ '204': OpenApiResponse(description='The annotation has been deleted'), }) @@ -1872,7 +1883,7 @@ def dataset_export(self, request, pk): callback=dm.views.export_job_as_dataset ) - @extend_schema(summary='Method returns data for a specific job', + @extend_schema(summary='Get data of a job', parameters=[ OpenApiParameter('type', description='Specifies the type of the requested data', location=OpenApiParameter.QUERY, required=False, type=OpenApiTypes.STR, @@ -1901,11 +1912,11 @@ def data(self, request, pk): db_job.segment.stop_frame, db_job.segment.task.data) - @extend_schema(summary='Method provides a meta information about media files which are related with the job', + @extend_schema(methods=['GET'], summary='Get metainformation for media files in a job', responses={ '200': DataMetaReadSerializer, }) - @extend_schema(methods=['PATCH'], summary='Method performs an update of data meta fields (deleted frames)', + @extend_schema(methods=['PATCH'], summary='Update metainformation for media files in a job', request=DataMetaWriteSerializer, responses={ '200': DataMetaReadSerializer, @@ -1983,7 +1994,7 @@ def metadata(self, request, pk): serializer = DataMetaReadSerializer(db_data) return Response(serializer.data) - @extend_schema(summary='Method returns a preview image for the job', + @extend_schema(summary='Get a preview image for a job', responses={ '200': OpenApiResponse(description='Job image preview'), }) @@ -2005,30 +2016,30 @@ def preview(self, request, pk): @extend_schema(tags=['issues']) @extend_schema_view( retrieve=extend_schema( - summary='Method returns details of an issue', + summary='Get issue details', responses={ '200': IssueReadSerializer, }), list=extend_schema( - summary='Method returns a paginated list of issues', + summary='List issues', responses={ '200': IssueReadSerializer(many=True), }), partial_update=extend_schema( - summary='Methods does a partial update of chosen fields in an issue', + summary='Update an issue', request=IssueWriteSerializer(partial=True), responses={ '200': IssueReadSerializer, # check IssueWriteSerializer.to_representation }), create=extend_schema( - summary='Method creates an issue', + summary='Create an issue', request=IssueWriteSerializer, parameters=ORGANIZATION_OPEN_API_PARAMETERS, responses={ '201': IssueReadSerializer, # check IssueWriteSerializer.to_representation }), destroy=extend_schema( - summary='Method deletes an issue', + summary='Delete an issue', responses={ '204': OpenApiResponse(description='The issue has been deleted'), }) @@ -2076,30 +2087,30 @@ def perform_create(self, serializer, **kwargs): @extend_schema(tags=['comments']) @extend_schema_view( retrieve=extend_schema( - summary='Method returns details of a comment', + summary='Get comment details', responses={ '200': CommentReadSerializer, }), list=extend_schema( - summary='Method returns a paginated list of comments', + summary='List comments', responses={ '200': CommentReadSerializer(many=True), }), partial_update=extend_schema( - summary='Methods does a partial update of chosen fields in a comment', + summary='Update a comment', request=CommentWriteSerializer(partial=True), responses={ '200': CommentReadSerializer, # check CommentWriteSerializer.to_representation }), create=extend_schema( - summary='Method creates a comment', + summary='Create a comment', request=CommentWriteSerializer, parameters=ORGANIZATION_OPEN_API_PARAMETERS, responses={ '201': CommentReadSerializer, # check CommentWriteSerializer.to_representation }), destroy=extend_schema( - summary='Method deletes a comment', + summary='Delete a comment', responses={ '204': OpenApiResponse(description='The comment has been deleted'), }) @@ -2147,12 +2158,12 @@ def perform_create(self, serializer, **kwargs): @extend_schema(tags=['labels']) @extend_schema_view( retrieve=extend_schema( - summary='Method returns details of a label', + summary='Get label details', responses={ '200': LabelSerializer, }), list=extend_schema( - summary='Method returns a paginated list of labels', + summary='List labels', parameters=[ # These filters are implemented differently from others OpenApiParameter('job_id', type=OpenApiTypes.INT, @@ -2167,15 +2178,15 @@ def perform_create(self, serializer, **kwargs): '200': LabelSerializer(many=True), }), partial_update=extend_schema( - summary='Methods does a partial update of chosen fields in a label' - 'To modify a sublabel, please use the PATCH method of the parent label', + summary='Update a label', + description='To modify a sublabel, please use the PATCH method of the parent label.', request=LabelSerializer(partial=True), responses={ '200': LabelSerializer, }), destroy=extend_schema( - summary='Method deletes a label. ' - 'To delete a sublabel, please use the PATCH method of the parent label', + summary='Delete a label', + description='To delete a sublabel, please use the PATCH method of the parent label.', responses={ '204': OpenApiResponse(description='The label has been deleted'), }) @@ -2294,7 +2305,7 @@ def perform_destroy(self, instance: models.Label): @extend_schema(tags=['users']) @extend_schema_view( list=extend_schema( - summary='Method returns a paginated list of users', + summary='List users', responses={ '200': PolymorphicProxySerializer( component_name='MetaUser', @@ -2307,7 +2318,7 @@ def perform_destroy(self, instance: models.Label): ), }), retrieve=extend_schema( - summary='Method provides information of a specific user', + summary='Get user details', responses={ '200': PolymorphicProxySerializer( component_name='MetaUser', @@ -2319,7 +2330,7 @@ def perform_destroy(self, instance: models.Label): ), }), partial_update=extend_schema( - summary='Method updates chosen fields of a user', + summary='Update a user', responses={ '200': PolymorphicProxySerializer( component_name='MetaUser', @@ -2331,7 +2342,7 @@ def perform_destroy(self, instance: models.Label): ), }), destroy=extend_schema( - summary='Method deletes a specific user from the server', + summary='Delete a user', responses={ '204': OpenApiResponse(description='The user has been deleted'), }) @@ -2372,7 +2383,7 @@ def get_serializer_class(self): else: return BasicUserSerializer - @extend_schema(summary='Method returns an instance of a user who is currently authorized', + @extend_schema(summary='Get details of the current user', responses={ '200': PolymorphicProxySerializer(component_name='MetaUser', serializers=[ @@ -2391,28 +2402,28 @@ def self(self, request): @extend_schema(tags=['cloudstorages']) @extend_schema_view( retrieve=extend_schema( - summary='Method returns details of a specific cloud storage', + summary='Get cloud storage details', responses={ '200': CloudStorageReadSerializer, }), list=extend_schema( - summary='Returns a paginated list of storages', + summary='List cloud storages', responses={ '200': CloudStorageReadSerializer(many=True), }), destroy=extend_schema( - summary='Method deletes a specific cloud storage', + summary='Delete a cloud storage', responses={ '204': OpenApiResponse(description='The cloud storage has been removed'), }), partial_update=extend_schema( - summary='Methods does a partial update of chosen fields in a cloud storage instance', + summary='Update a cloud storage', request=CloudStorageWriteSerializer(partial=True), responses={ '200': CloudStorageReadSerializer, # check CloudStorageWriteSerializer.to_representation }), create=extend_schema( - summary='Method creates a cloud storage with a specified characteristics', + summary='Create a cloud storage', request=CloudStorageWriteSerializer, parameters=ORGANIZATION_OPEN_API_PARAMETERS, responses={ @@ -2479,7 +2490,7 @@ def create(self, request, *args, **kwargs): response = HttpResponseBadRequest(str(ex)) return response - @extend_schema(summary='Method returns the content of the cloud storage', + @extend_schema(summary='Get cloud storage content', parameters=[ OpenApiParameter('manifest_path', description='Path to the manifest file in a cloud storage', location=OpenApiParameter.QUERY, type=OpenApiTypes.STR), @@ -2554,7 +2565,7 @@ def content_v2(self, request, pk): return Response("An internal error has occurred", status=status.HTTP_500_INTERNAL_SERVER_ERROR) - @extend_schema(summary='Method returns a preview image from a cloud storage', + @extend_schema(summary='Get a preview image for a cloud storage', responses={ '200': OpenApiResponse(description='Cloud Storage preview'), '400': OpenApiResponse(description='Failed to get cloud storage preview'), @@ -2590,7 +2601,7 @@ def preview(self, request, pk): return Response("An internal error has occurred", status=status.HTTP_500_INTERNAL_SERVER_ERROR) - @extend_schema(summary='Method returns a cloud storage status', + @extend_schema(summary='Get the status of a cloud storage', responses={ '200': OpenApiResponse(response=OpenApiTypes.STR, description='Cloud Storage status (AVAILABLE | NOT_FOUND | FORBIDDEN)'), }) @@ -2609,7 +2620,7 @@ def status(self, request, pk): msg = str(ex) return HttpResponseBadRequest(msg) - @extend_schema(summary='Method returns allowed actions for the cloud storage', + @extend_schema(summary='Get allowed actions for a cloud storage', responses={ '200': OpenApiResponse(response=OpenApiTypes.STR, description='Cloud Storage actions (GET | PUT | DELETE)'), }) @@ -2634,7 +2645,7 @@ def actions(self, request, pk): @extend_schema(tags=['assets']) @extend_schema_view( create=extend_schema( - summary='Method saves new asset on the server and attaches it to a corresponding guide', + summary='Create an asset', request={ 'multipart/form-data': { 'type': 'object', @@ -2650,12 +2661,12 @@ def actions(self, request, pk): '201': AssetReadSerializer, }), retrieve=extend_schema( - summary='Method returns an asset file', + summary='Get an asset', responses={ '200': OpenApiResponse(description='Asset file') }), destroy=extend_schema( - summary='Method deletes a specific asset from the server', + summary='Delete an asset', responses={ '204': OpenApiResponse(description='The asset has been deleted'), }), @@ -2741,23 +2752,25 @@ def perform_destroy(self, instance): @extend_schema(tags=['guides']) @extend_schema_view( create=extend_schema( - summary='Method creates a new annotation guide binded to a project or to a task', + summary='Create an annotation guide', + description='The new guide will be bound either to a project or a task, depending on parameters.', request=AnnotationGuideWriteSerializer, responses={ '201': AnnotationGuideReadSerializer, }), retrieve=extend_schema( - summary='Method returns details of a specific annotation guide', + summary='Get annotation guide details', responses={ '200': AnnotationGuideReadSerializer, }), destroy=extend_schema( - summary='Method deletes a specific annotation guide and all attached assets', + summary='Delete an annotation guide', + description='This also deletes all assets attached to the guide.', responses={ '204': OpenApiResponse(description='The annotation guide has been deleted'), }), partial_update=extend_schema( - summary='Methods does a partial update of chosen fields in an annotation guide', + summary='Update an annotation guide', request=AnnotationGuideWriteSerializer(partial=True), responses={ '200': AnnotationGuideReadSerializer, # check TaskWriteSerializer.to_representation diff --git a/cvat/apps/events/views.py b/cvat/apps/events/views.py index f208efb9e81b..1281592d9e7d 100644 --- 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 index feceea06607f..0f45997ef2d6 100644 --- 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,37 +151,37 @@ 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'), @@ -189,13 +189,13 @@ def get_queryset(self): 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 index b16b3d12f419..030818e17fc0 100644 --- 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 index afc725fa83b6..5f55312787d8 100644 --- a/cvat/apps/webhooks/views.py +++ b/cvat/apps/webhooks/views.py @@ -24,22 +24,22 @@ @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 @@ -47,14 +47,14 @@ ), 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}, ) diff --git a/cvat/schema.yml b/cvat/schema.yml index b66048b72892..9ff8d3a308fe 100644 --- a/cvat/schema.yml +++ b/cvat/schema.yml @@ -16,7 +16,7 @@ paths: get: operationId: analytics_get_reports description: Receive analytics report - summary: Method returns analytics report + summary: Get an analytics report parameters: - in: query name: end_date @@ -64,8 +64,7 @@ paths: description: Not found post: operationId: analytics_create_report - summary: Creates a analytics report asynchronously and allows to check request - status + summary: Create an analytics report parameters: - in: query name: rq_id @@ -105,8 +104,7 @@ paths: /api/assets: post: operationId: assets_create - summary: Method saves new asset on the server and attaches it to a corresponding - guide + summary: Create an asset tags: - assets requestBody: @@ -134,7 +132,7 @@ paths: /api/assets/{uuid}: get: operationId: assets_retrieve - summary: Method returns an asset file + summary: Get an asset parameters: - in: path name: uuid @@ -156,7 +154,7 @@ paths: description: Asset file delete: operationId: assets_destroy - summary: Method deletes a specific asset from the server + summary: Delete an asset parameters: - in: path name: uuid @@ -391,7 +389,7 @@ paths: /api/cloudstorages: get: operationId: cloudstorages_list - summary: Returns a paginated list of storages + summary: List cloud storages parameters: - name: X-Organization in: header @@ -504,7 +502,7 @@ paths: description: '' post: operationId: cloudstorages_create - summary: Method creates a cloud storage with a specified characteristics + summary: Create a cloud storage parameters: - in: header name: X-Organization @@ -592,7 +590,7 @@ paths: /api/cloudstorages/{id}: get: operationId: cloudstorages_retrieve - summary: Method returns details of a specific cloud storage + summary: Get cloud storage details parameters: - in: path name: id @@ -617,7 +615,7 @@ paths: description: '' patch: operationId: cloudstorages_partial_update - summary: Methods does a partial update of chosen fields in a cloud storage instance + summary: Update a cloud storage parameters: - in: path name: id @@ -694,7 +692,7 @@ paths: description: '' delete: operationId: cloudstorages_destroy - summary: Method deletes a specific cloud storage + summary: Delete a cloud storage parameters: - in: path name: id @@ -718,7 +716,7 @@ paths: operationId: cloudstorages_retrieve_actions description: Method return allowed actions for cloud storage. It's required for reading/writing - summary: Method returns allowed actions for the cloud storage + summary: Get allowed actions for a cloud storage parameters: - in: path name: id @@ -744,7 +742,7 @@ paths: /api/cloudstorages/{id}/content-v2: get: operationId: cloudstorages_retrieve_content_v2 - summary: Method returns the content of the cloud storage + summary: Get cloud storage content parameters: - in: path name: id @@ -789,7 +787,7 @@ paths: /api/cloudstorages/{id}/preview: get: operationId: cloudstorages_retrieve_preview - summary: Method returns a preview image from a cloud storage + summary: Get a preview image for a cloud storage parameters: - in: path name: id @@ -815,7 +813,7 @@ paths: /api/cloudstorages/{id}/status: get: operationId: cloudstorages_retrieve_status - summary: Method returns a cloud storage status + summary: Get the status of a cloud storage parameters: - in: path name: id @@ -841,7 +839,7 @@ paths: /api/comments: get: operationId: comments_list - summary: Method returns a paginated list of comments + summary: List comments parameters: - name: X-Organization in: header @@ -936,7 +934,7 @@ paths: description: '' post: operationId: comments_create - summary: Method creates a comment + summary: Create a comment parameters: - in: header name: X-Organization @@ -977,7 +975,7 @@ paths: /api/comments/{id}: get: operationId: comments_retrieve - summary: Method returns details of a comment + summary: Get comment details parameters: - in: path name: id @@ -1002,7 +1000,7 @@ paths: description: '' patch: operationId: comments_partial_update - summary: Methods does a partial update of chosen fields in a comment + summary: Update a comment parameters: - in: path name: id @@ -1032,7 +1030,7 @@ paths: description: '' delete: operationId: comments_destroy - summary: Method deletes a comment + summary: Delete a comment parameters: - in: path name: id @@ -1054,8 +1052,8 @@ paths: /api/events: get: operationId: events_list - description: Receive logs from the server - summary: 'Method returns csv log file ' + description: The log is returned in the CSV format. + summary: Get an event log parameters: - in: query name: action @@ -1132,7 +1130,7 @@ paths: post: operationId: events_create description: Sends logs to the Clickhouse if it is connected - summary: Method saves logs from a client on the server + summary: Log client events parameters: - in: header name: X-Organization @@ -1173,7 +1171,9 @@ paths: /api/guides: post: operationId: guides_create - summary: Method creates a new annotation guide binded to a project or to a task + description: The new guide will be bound either to a project or a task, depending + on parameters. + summary: Create an annotation guide tags: - guides requestBody: @@ -1197,7 +1197,7 @@ paths: /api/guides/{id}: get: operationId: guides_retrieve - summary: Method returns details of a specific annotation guide + summary: Get annotation guide details parameters: - in: path name: id @@ -1222,7 +1222,7 @@ paths: description: '' patch: operationId: guides_partial_update - summary: Methods does a partial update of chosen fields in an annotation guide + summary: Update an annotation guide parameters: - in: path name: id @@ -1252,7 +1252,8 @@ paths: description: '' delete: operationId: guides_destroy - summary: Method deletes a specific annotation guide and all attached assets + description: This also deletes all assets attached to the guide. + summary: Delete an annotation guide parameters: - in: path name: id @@ -1274,7 +1275,7 @@ paths: /api/invitations: get: operationId: invitations_list - summary: Method returns a paginated list of invitations + summary: List invitations parameters: - name: X-Organization in: header @@ -1354,7 +1355,7 @@ paths: description: '' post: operationId: invitations_create - summary: Method creates an invitation + summary: Create an invitation parameters: - in: header name: X-Organization @@ -1395,7 +1396,7 @@ paths: /api/invitations/{key}: get: operationId: invitations_retrieve - summary: Method returns details of an invitation + summary: Get invitation details parameters: - in: path name: key @@ -1420,7 +1421,7 @@ paths: description: '' patch: operationId: invitations_partial_update - summary: Methods does a partial update of chosen fields in an invitation + summary: Update an invitation parameters: - in: path name: key @@ -1450,7 +1451,7 @@ paths: description: '' delete: operationId: invitations_destroy - summary: Method deletes an invitation + summary: Delete an invitation parameters: - in: path name: key @@ -1472,7 +1473,7 @@ paths: /api/invitations/{key}/accept: post: operationId: invitations_accept - summary: Method registers user and accepts invitation to organization + summary: Accept an invitation parameters: - in: path name: key @@ -1500,7 +1501,7 @@ paths: /api/invitations/{key}/decline: post: operationId: invitations_decline - summary: Method declines the invitation to organization + summary: Decline an invitation parameters: - in: path name: key @@ -1522,7 +1523,7 @@ paths: /api/invitations/{key}/resend: post: operationId: invitations_resend - summary: Method resends the invitation to organization + summary: Resend an invitation parameters: - in: path name: key @@ -1546,7 +1547,7 @@ paths: /api/issues: get: operationId: issues_list - summary: Method returns a paginated list of issues + summary: List issues parameters: - name: X-Organization in: header @@ -1652,7 +1653,7 @@ paths: description: '' post: operationId: issues_create - summary: Method creates an issue + summary: Create an issue parameters: - in: header name: X-Organization @@ -1693,7 +1694,7 @@ paths: /api/issues/{id}: get: operationId: issues_retrieve - summary: Method returns details of an issue + summary: Get issue details parameters: - in: path name: id @@ -1718,7 +1719,7 @@ paths: description: '' patch: operationId: issues_partial_update - summary: Methods does a partial update of chosen fields in an issue + summary: Update an issue parameters: - in: path name: id @@ -1748,7 +1749,7 @@ paths: description: '' delete: operationId: issues_destroy - summary: Method deletes an issue + summary: Delete an issue parameters: - in: path name: id @@ -1770,7 +1771,7 @@ paths: /api/jobs: get: operationId: jobs_list - summary: Method returns a paginated list of jobs + summary: List jobs parameters: - name: X-Organization in: header @@ -1907,7 +1908,7 @@ paths: description: '' post: operationId: jobs_create - summary: Method creates a new job in the task + summary: Create a job tags: - jobs requestBody: @@ -1932,7 +1933,7 @@ paths: /api/jobs/{id}: get: operationId: jobs_retrieve - summary: Method returns details of a job + summary: Get job details parameters: - in: path name: id @@ -1957,7 +1958,7 @@ paths: description: '' patch: operationId: jobs_partial_update - summary: Methods does a partial update of chosen fields in a job + summary: Update a job parameters: - in: path name: id @@ -1988,9 +1989,11 @@ paths: delete: operationId: jobs_destroy description: | + Related annotations will be deleted as well. + Please note, that not every job can be removed. Currently, it is only available for Ground Truth jobs. - summary: Method deletes a job and its related annotations + summary: Delete a job parameters: - in: path name: id @@ -2012,8 +2015,10 @@ paths: /api/jobs/{id}/annotations/: get: operationId: jobs_retrieve_annotations - summary: Method returns annotations for a specific job as a JSON document. If - format is specified, a zip archive is returned. + description: | + If format is specified, a ZIP archive will be returned. Otherwise, + the annotations will be returned as a JSON document. + summary: Get job annotations parameters: - in: query name: action @@ -2086,11 +2091,10 @@ paths: operationId: jobs_create_annotations description: |2 - The request POST /api/jobs/id/annotations will initiate file upload and will create - the rq job on the server in which the process of annotations uploading from file - will be carried out. Please, use the PUT /api/jobs/id/annotations endpoint for checking status of the process. - summary: Method allows to initialize the process of the job annotation upload - from a local file or a cloud storage + The request POST /api/jobs/id/annotations will initiate the import and will create + the rq job on the server in which the import will be carried out. + Please, use the PUT /api/jobs/id/annotations endpoint for checking status of the process. + summary: Import annotations into a job parameters: - in: query name: cloud_storage_id @@ -2161,13 +2165,12 @@ paths: operationId: jobs_update_annotations description: |2 - To check the status of the process of uploading a job annotations from a file: + To check the status of an import request: - After initiating the annotations upload, you will receive an rq_id parameter. + After initiating the annotation import, you will receive an rq_id parameter. Make sure to include this parameter as a query parameter in your subsequent - PUT /api/jobs/id/annotations requests to track the status of the annotations upload. - summary: Method performs an update of all annotations in a specific job or used - for uploading annotations from a file + PUT /api/jobs/id/annotations requests to track the status of the import. + summary: Replace job annotations / Get annotation import status parameters: - in: query name: cloud_storage_id @@ -2230,14 +2233,14 @@ paths: - basicAuth: [] responses: '201': - description: Uploading has finished + description: Import has finished '202': - description: Uploading has been started + description: Import is in progress '405': description: Format is not available patch: operationId: jobs_partial_update_annotations - summary: Method performs a partial update of annotations in a specific job + summary: Update job annotations parameters: - in: query name: action @@ -2275,7 +2278,7 @@ paths: description: Annotations successfully uploaded delete: operationId: jobs_destroy_annotations - summary: Method deletes all annotations for a specific job + summary: Delete job annotations parameters: - in: path name: id @@ -2297,7 +2300,7 @@ paths: /api/jobs/{id}/data: get: operationId: jobs_retrieve_data - summary: Method returns data for a specific job + summary: Get data of a job parameters: - in: path name: id @@ -2346,8 +2349,7 @@ paths: /api/jobs/{id}/data/meta: get: operationId: jobs_retrieve_data_meta - summary: Method provides a meta information about media files which are related - with the job + summary: Get metainformation for media files in a job parameters: - in: path name: id @@ -2372,8 +2374,7 @@ paths: description: '' patch: operationId: jobs_partial_update_data_meta - summary: Method provides a meta information about media files which are related - with the job + summary: Update metainformation for media files in a job parameters: - in: path name: id @@ -2478,7 +2479,7 @@ paths: /api/jobs/{id}/preview: get: operationId: jobs_retrieve_preview - summary: Method returns a preview image for the job + summary: Get a preview image for a job parameters: - in: path name: id @@ -2500,7 +2501,7 @@ paths: /api/labels: get: operationId: labels_list - summary: Method returns a paginated list of labels + summary: List labels parameters: - in: header name: X-Organization @@ -2627,7 +2628,7 @@ paths: /api/labels/{id}: get: operationId: labels_retrieve - summary: Method returns details of a label + summary: Get label details parameters: - in: path name: id @@ -2652,8 +2653,9 @@ paths: description: '' patch: operationId: labels_partial_update - summary: Methods does a partial update of chosen fields in a labelTo modify - a sublabel, please use the PATCH method of the parent label + description: To modify a sublabel, please use the PATCH method of the parent + label. + summary: Update a label parameters: - in: path name: id @@ -2683,8 +2685,9 @@ paths: description: '' delete: operationId: labels_destroy - summary: Method deletes a label. To delete a sublabel, please use the PATCH - method of the parent label + description: To delete a sublabel, please use the PATCH method of the parent + label. + summary: Delete a label parameters: - in: path name: id @@ -2888,7 +2891,7 @@ paths: /api/memberships: get: operationId: memberships_list - summary: Method returns a paginated list of memberships + summary: List memberships parameters: - name: X-Organization in: header @@ -2979,7 +2982,7 @@ paths: /api/memberships/{id}: get: operationId: memberships_retrieve - summary: Method returns details of a membership + summary: Get membership details parameters: - in: path name: id @@ -3004,7 +3007,7 @@ paths: description: '' patch: operationId: memberships_partial_update - summary: Methods does a partial update of chosen fields in a membership + summary: Update a membership parameters: - in: path name: id @@ -3034,7 +3037,7 @@ paths: description: '' delete: operationId: memberships_destroy - summary: Method deletes a membership + summary: Delete a membership parameters: - in: path name: id @@ -3056,7 +3059,7 @@ paths: /api/organizations: get: operationId: organizations_list - summary: Method returns a paginated list of organizations + summary: List organizations parameters: - name: filter required: false @@ -3132,7 +3135,7 @@ paths: description: '' post: operationId: organizations_create - summary: Method creates an organization + summary: Create an organization tags: - organizations requestBody: @@ -3157,7 +3160,7 @@ paths: /api/organizations/{id}: get: operationId: organizations_retrieve - summary: Method returns details of an organization + summary: Get organization details parameters: - in: path name: id @@ -3182,7 +3185,7 @@ paths: description: '' patch: operationId: organizations_partial_update - summary: Methods does a partial update of chosen fields in an organization + summary: Update an organization parameters: - in: path name: id @@ -3212,7 +3215,7 @@ paths: description: '' delete: operationId: organizations_destroy - summary: Method deletes an organization + summary: Delete an organization parameters: - in: path name: id @@ -3234,7 +3237,7 @@ paths: /api/projects: get: operationId: projects_list - summary: Returns a paginated list of projects + summary: List projects parameters: - name: X-Organization in: header @@ -3334,7 +3337,7 @@ paths: description: '' post: operationId: projects_create - summary: Method creates a new project + summary: Create a project parameters: - in: header name: X-Organization @@ -3375,7 +3378,7 @@ paths: /api/projects/{id}: get: operationId: projects_retrieve - summary: Method returns details of a specific project + summary: Get project details parameters: - in: path name: id @@ -3400,7 +3403,7 @@ paths: description: '' patch: operationId: projects_partial_update - summary: Methods does a partial update of chosen fields in a project + summary: Update a project parameters: - in: path name: id @@ -3430,7 +3433,7 @@ paths: description: '' delete: operationId: projects_destroy - summary: Method deletes a specific project + summary: Delete a project parameters: - in: path name: id @@ -3452,7 +3455,7 @@ paths: /api/projects/{id}/annotations: get: operationId: projects_retrieve_annotations - summary: Method allows to download project annotations + summary: Get project annotations parameters: - in: query name: action @@ -3527,7 +3530,7 @@ paths: /api/projects/{id}/backup: get: operationId: projects_retrieve_backup - summary: Methods creates a backup copy of a project + summary: Back up a project parameters: - in: query name: action @@ -3593,7 +3596,7 @@ paths: Make sure to include this parameter as a query parameter in your subsequent GET /api/projects/id/dataset requests to track the status of the dataset import. Also you should specify action parameter: action=import_status. - summary: Export project as a dataset in a specific format + summary: Export a project as a dataset / Check dataset import status parameters: - in: query name: action @@ -3676,8 +3679,7 @@ paths: The request POST /api/projects/id/dataset will initiate file upload and will create the rq job on the server in which the process of dataset import from a file will be carried out. Please, use the GET /api/projects/id/dataset endpoint for checking status of the process. - summary: Import dataset in specific format as a project or check status of dataset - import process + summary: Import a dataset into a project parameters: - in: query name: cloud_storage_id @@ -3748,7 +3750,7 @@ paths: /api/projects/{id}/preview: get: operationId: projects_retrieve_preview - summary: Method returns a preview image for the project + summary: Get a preview image for a project parameters: - in: path name: id @@ -3784,7 +3786,7 @@ paths: Make sure to include this parameter as a query parameter in your subsequent requests to track the status of the project creation. Once the project has been successfully created, the server will return the id of the newly created project. - summary: Methods create a project from a backup + summary: Recreate a project from a backup parameters: - in: header name: X-Organization @@ -3853,7 +3855,7 @@ paths: /api/quality/conflicts: get: operationId: quality_list_conflicts - summary: Method returns a paginated list of annotation conflicts + summary: List annotation conflicts in a quality report parameters: - name: X-Organization in: header @@ -3965,7 +3967,7 @@ paths: /api/quality/reports: get: operationId: quality_list_reports - summary: Method returns a paginated list of quality reports + summary: List quality reports parameters: - name: X-Organization in: header @@ -4055,8 +4057,7 @@ paths: description: '' post: operationId: quality_create_report - summary: Creates a quality report asynchronously and allows to check request - status + summary: Create a quality report parameters: - in: query name: rq_id @@ -4100,7 +4101,7 @@ paths: /api/quality/reports/{id}: get: operationId: quality_retrieve_report - summary: Method returns details of a quality report + summary: Get quality report details parameters: - in: path name: id @@ -4126,7 +4127,7 @@ paths: /api/quality/reports/{id}/data: get: operationId: quality_retrieve_report_data - summary: Retrieve full contents of the report in JSON format + summary: Get quality report contents parameters: - in: path name: id @@ -4152,7 +4153,7 @@ paths: /api/quality/settings: get: operationId: quality_list_settings - summary: Method returns a paginated list of quality settings instances + summary: List quality settings instances parameters: - name: X-Organization in: header @@ -4227,7 +4228,7 @@ paths: /api/quality/settings/{id}: get: operationId: quality_retrieve_settings - summary: Method returns details of the quality settings instance + summary: Get quality settings instance details parameters: - in: path name: id @@ -4252,8 +4253,7 @@ paths: description: '' patch: operationId: quality_partial_update_settings - summary: Methods does a partial update of chosen fields in the quality settings - instance + summary: Update a quality settings instance parameters: - in: path name: id @@ -4427,7 +4427,7 @@ paths: /api/server/about: get: operationId: server_retrieve_about - summary: Method provides basic CVAT information + summary: Get basic CVAT information tags: - server security: @@ -4446,7 +4446,7 @@ paths: /api/server/annotation/formats: get: operationId: server_retrieve_annotation_formats - summary: Method provides the list of supported annotations formats + summary: Get supported annotation formats tags: - server security: @@ -4465,7 +4465,7 @@ paths: /api/server/plugins: get: operationId: server_retrieve_plugins - summary: Method provides allowed plugins + summary: Get enabled plugins tags: - server security: @@ -4484,8 +4484,7 @@ paths: /api/server/share: get: operationId: server_list_share - summary: Returns all files and folders that are on the server along specified - path + summary: List files/directories in the mounted share parameters: - in: query name: directory @@ -4517,7 +4516,7 @@ paths: /api/tasks: get: operationId: tasks_list - summary: Returns a paginated list of tasks + summary: List tasks parameters: - name: X-Organization in: header @@ -4659,8 +4658,10 @@ paths: description: '' post: operationId: tasks_create - summary: Method creates a new task in a database without any attached images - and videos + description: | + The new task will not have any attached images or videos. + To attach them, use the /api/tasks//data endpoint. + summary: Create a task parameters: - in: header name: X-Organization @@ -4701,7 +4702,7 @@ paths: /api/tasks/{id}: get: operationId: tasks_retrieve - summary: Method returns details of a specific task + summary: Get task details parameters: - in: path name: id @@ -4726,7 +4727,7 @@ paths: description: '' patch: operationId: tasks_partial_update - summary: Methods does a partial update of chosen fields in a task + summary: Update a task parameters: - in: path name: id @@ -4756,8 +4757,8 @@ paths: description: '' delete: operationId: tasks_destroy - summary: Method deletes a specific task, all attached jobs, annotations, and - data + description: All attached jobs, annotations and data will be deleted as well. + summary: Delete a task parameters: - in: path name: id @@ -4779,7 +4780,7 @@ paths: /api/tasks/{id}/annotations/: get: operationId: tasks_retrieve_annotations - summary: Method allows to download task annotations + summary: Get task annotations parameters: - in: query name: action @@ -4854,11 +4855,10 @@ paths: operationId: tasks_create_annotations description: |2 - The request POST /api/tasks/id/annotations will initiate file upload and will create - the rq job on the server in which the process of annotations uploading from file - will be carried out. Please, use the PUT /api/tasks/id/annotations endpoint for checking status of the process. - summary: Method allows to initialize the process of upload task annotations - from a local or a cloud storage file + The request POST /api/tasks/id/annotations will initiate the import and will create + the rq job on the server in which the import will be carried out. + Please, use the PUT /api/tasks/id/annotations endpoint for checking status of the process. + summary: Import annotations into a task parameters: - in: query name: cloud_storage_id @@ -4929,12 +4929,12 @@ paths: operationId: tasks_update_annotations description: |2 - To check the status of the process of uploading a task annotations from a file: + To check the status of an import request: - After initiating the annotations upload, you will receive an rq_id parameter. + After initiating the annotation import, you will receive an rq_id parameter. Make sure to include this parameter as a query parameter in your subsequent - PUT /api/tasks/id/annotations requests to track the status of the annotations upload. - summary: Method allows to upload task annotations or edit existing annotations + PUT /api/tasks/id/annotations requests to track the status of the import. + summary: Replace task annotations / Get annotation import status parameters: - in: query name: format @@ -4973,14 +4973,14 @@ paths: - basicAuth: [] responses: '201': - description: Uploading has finished + description: Import has finished '202': - description: Uploading has been started + description: Import is in progress '405': description: Format is not available patch: operationId: tasks_partial_update_annotations - summary: Method performs a partial update of annotations in a specific task + summary: Update task annotations parameters: - in: query name: action @@ -5022,7 +5022,7 @@ paths: description: '' delete: operationId: tasks_destroy_annotations - summary: Method deletes all annotations for a specific task + summary: Delete task annotations parameters: - in: path name: id @@ -5044,7 +5044,7 @@ paths: /api/tasks/{id}/backup: get: operationId: tasks_retrieve_backup - summary: Method backup a specified task + summary: Back up a task parameters: - in: query name: action @@ -5104,7 +5104,7 @@ paths: /api/tasks/{id}/data/: get: operationId: tasks_retrieve_data - summary: Method returns data for a specific task + summary: Get data of a task parameters: - in: path name: id @@ -5148,7 +5148,7 @@ paths: post: operationId: tasks_create_data description: | - Allows to upload data to a task. + Allows to upload data (images, video, etc.) to a task. Supports the TUS open file uploading protocol (https://tus.io/). Supports the following protocols: @@ -5197,7 +5197,9 @@ paths: After all data is sent, the operation status can be retrieved via the /status endpoint. - summary: Method permanently attaches data (images, video, etc.) to a task + + Once data is attached to a task, it cannot be detached or replaced. + summary: Attach data to a task parameters: - in: header name: Upload-Finish @@ -5245,8 +5247,7 @@ paths: /api/tasks/{id}/data/meta: get: operationId: tasks_retrieve_data_meta - summary: Method provides a meta information about media files which are related - with the task + summary: Get metainformation for media files in a task parameters: - in: path name: id @@ -5271,8 +5272,7 @@ paths: description: '' patch: operationId: tasks_partial_update_data_meta - summary: Method provides a meta information about media files which are related - with the task + summary: Update metainformation for media files in a task parameters: - in: path name: id @@ -5379,7 +5379,7 @@ paths: /api/tasks/{id}/preview: get: operationId: tasks_retrieve_preview - summary: Method returns a preview image for the task + summary: Get a preview image for a task parameters: - in: path name: id @@ -5403,8 +5403,7 @@ paths: /api/tasks/{id}/status: get: operationId: tasks_retrieve_status - summary: When task is being created the method returns information about a status - of the creation process + summary: Get the creation status of a task parameters: - in: path name: id @@ -5442,7 +5441,7 @@ paths: Make sure to include this parameter as a query parameter in your subsequent requests to track the status of the task creation. Once the task has been successfully created, the server will return the id of the newly created task. - summary: Method recreates a task from an attached task backup file + summary: Recreate a task from a backup parameters: - in: header name: X-Organization @@ -5511,7 +5510,7 @@ paths: /api/users: get: operationId: users_list - summary: Method returns a paginated list of users + summary: List users parameters: - name: X-Organization in: header @@ -5608,7 +5607,7 @@ paths: /api/users/{id}: get: operationId: users_retrieve - summary: Method provides information of a specific user + summary: Get user details parameters: - in: path name: id @@ -5633,7 +5632,7 @@ paths: description: '' patch: operationId: users_partial_update - summary: Method updates chosen fields of a user + summary: Update a user parameters: - in: path name: id @@ -5663,7 +5662,7 @@ paths: description: '' delete: operationId: users_destroy - summary: Method deletes a specific user from the server + summary: Delete a user parameters: - in: path name: id @@ -5686,7 +5685,7 @@ paths: get: operationId: users_retrieve_self description: Method returns an instance of a user who is currently authorized - summary: Method returns an instance of a user who is currently authorized + summary: Get details of the current user tags: - users security: @@ -5705,7 +5704,7 @@ paths: /api/webhooks: get: operationId: webhooks_list - summary: Method returns a paginated list of webhook according to query parameters + summary: List webhooks parameters: - name: X-Organization in: header @@ -5805,7 +5804,7 @@ paths: description: '' post: operationId: webhooks_create - summary: Method creates a webhook + summary: Create a webhook parameters: - in: header name: X-Organization @@ -5846,7 +5845,7 @@ paths: /api/webhooks/{id}: get: operationId: webhooks_retrieve - summary: Method returns details of a webhook + summary: Get webhook details parameters: - in: path name: id @@ -5871,7 +5870,7 @@ paths: description: '' put: operationId: webhooks_update - summary: Method updates a webhook by id + summary: Replace a webhook parameters: - in: path name: id @@ -5902,7 +5901,7 @@ paths: description: '' patch: operationId: webhooks_partial_update - summary: Methods does a partial update of chosen fields in a webhook + summary: Update a webhook parameters: - in: path name: id @@ -5932,7 +5931,7 @@ paths: description: '' delete: operationId: webhooks_destroy - summary: Method deletes a webhook + summary: Delete a webhook parameters: - in: path name: id @@ -5954,7 +5953,7 @@ paths: /api/webhooks/{id}/deliveries: get: operationId: webhooks_list_deliveries - summary: Method return a list of deliveries for a specific webhook + summary: List deliveries for a webhook parameters: - in: path name: id @@ -5992,7 +5991,7 @@ paths: /api/webhooks/{id}/deliveries/{delivery_id}: get: operationId: webhooks_retrieve_deliveries - summary: Method return a specific delivery for a specific webhook + summary: Get details of a webhook delivery parameters: - in: path name: delivery_id @@ -6024,7 +6023,7 @@ paths: /api/webhooks/{id}/deliveries/{delivery_id}/redelivery: post: operationId: webhooks_create_deliveries_redelivery - summary: Method redeliver a specific webhook delivery + summary: Redeliver a webhook delivery parameters: - in: path name: delivery_id @@ -6052,7 +6051,7 @@ paths: /api/webhooks/{id}/ping: post: operationId: webhooks_create_ping - summary: Method send ping webhook + summary: Send a ping webhook parameters: - in: path name: id @@ -6078,7 +6077,7 @@ paths: /api/webhooks/events: get: operationId: webhooks_retrieve_events - summary: Method return a list of available webhook events + summary: List available webhook events parameters: - in: query name: type