Merge branch 'rewrite-operation-id-and-descriptions' into 'master'

Rewrite operationId and description from patch.yml

Closes #647

See merge request !1235

arkindex/dataimport/api.py

@@ -195,6 +195,9 @@ class DataImportsList(CorpusACLMixin, ListAPIView):
 
 
 @extend_schema(tags=['imports'])
+@extend_schema_view(
+    delete=extend_schema(description='Delete a data import. Cannot be used on currently running data imports.')
+)
 class DataImportDetails(CorpusACLMixin, RetrieveUpdateDestroyAPIView):
     """
     Retrieve or edit a process
@@ -430,6 +433,12 @@ class DataFileList(CorpusACLMixin, ListAPIView):
 
 
 @extend_schema(tags=['files'])
+@extend_schema_view(
+    get=extend_schema(description="Get an uploaded file's metadata"),
+    patch=extend_schema(description="Update a datafile's status"),
+    put=extend_schema(description="Update a datafile's status"),
+    delete=extend_schema(description='Delete an uploaded file')
+)
 class DataFileRetrieve(CorpusACLMixin, RetrieveUpdateDestroyAPIView):
     """
     Get one file
@@ -595,6 +604,9 @@ class AvailableRepositoriesList(ListCreateAPIView):
     tags=['repos'],
     description='Retrieve a repository',
 )
+@extend_schema_view(
+    delete=extend_schema(description="Delete a repository")
+)
 class RepositoryRetrieve(RepositoryACLMixin, RetrieveDestroyAPIView):
     """
     Retrieve a repository

arkindex/documents/api/elements.py

@@ -565,6 +565,12 @@ class ElementChildren(ElementsListBase):
 
 
 @extend_schema(tags=['elements'])
+@extend_schema_view(
+    get=extend_schema(description="Retrieve a single element's informations and metadata"),
+    patch=extend_schema(description='Rename an element'),
+    put=extend_schema(description='Rename an element'),
+    delete=extend_schema(description='Delete an element'),
+)
 class ElementRetrieve(ACLMixin, RetrieveUpdateDestroyAPIView):
     """
     Retrieve a single element
@@ -659,6 +665,10 @@ class ElementNeighbors(ListAPIView):
 
 
 @extend_schema(tags=['elements'])
+@extend_schema_view(
+    post=extend_schema(operation_id='CreateElementParent', description='Link an element to a new parent'),
+    delete=extend_schema(operation_id='DestroyElementParent', description='Delete the relation between an element and one of its parents'),
+)
 class ElementParent(CreateAPIView, DestroyAPIView):
     """
     Manage element relation with one of its parents
@@ -700,6 +710,14 @@ class ElementParent(CreateAPIView, DestroyAPIView):
                 required=False,
             ),
         ],
+    ),
+    post=extend_schema(
+        operation_id='AddSelection',
+        description='Add specific elements'
+    ),
+    delete=extend_schema(
+        operation_id='RemoveSelection',
+        description='Remove a specific element or delete any selection'
     )
 )
 class ManageSelection(SelectionMixin, ListAPIView):
@@ -771,6 +789,10 @@ class ManageSelection(SelectionMixin, ListAPIView):
 
 
 @extend_schema(tags=['corpora'])
+@extend_schema_view(
+    get=extend_schema(description='List corpora with their access rights'),
+    post=extend_schema(description='Create a new corpus'),
+)
 class CorpusList(ListCreateAPIView):
     """
     List all available corpora and create new ones
@@ -802,6 +824,17 @@ class CorpusList(ListCreateAPIView):
 
 
 @extend_schema(tags=['corpora'])
+@extend_schema_view(
+    get=extend_schema(description='Retrieve a single corpus'),
+    put=extend_schema(description='Update a corpus'),
+    patch=extend_schema(description='Partially update a corpus'),
+    delete=extend_schema(
+        description='Delete a corpus. Requires the "admin" right on the corpus. '
+                    'This triggers an asynchronous deletion of a corpus and returns a '
+                    'response immediately; the actual deletion will become visible once '
+                    'the process is completed.'
+    ),
+)
 class CorpusRetrieve(ACLMixin, RetrieveUpdateDestroyAPIView):
     """
     Get, update and delete corpora
@@ -986,6 +1019,12 @@ class ElementMetadata(ListCreateAPIView):
 
 
 @extend_schema(tags=['elements'])
+@extend_schema_view(
+    get=extend_schema(operation_id='RetrieveMetaData', description='Retrieve an existing metadata'),
+    patch=extend_schema(operation_id='PartialUpdateMetaData', description='Partially update an existing metadata'),
+    put=extend_schema(operation_id='UpdateMetaData', description='Update an existing metadata'),
+    delete=extend_schema(operation_id='DestroyMetaData', description='Delete an existing metadata')
+)
 class MetadataEdit(ACLMixin, RetrieveUpdateDestroyAPIView):
     """
     Edit an existing element medadata

arkindex/documents/api/entities.py

@@ -47,6 +47,10 @@ logger = logging.getLogger(__name__)
 
 
 @extend_schema(tags=['entities'])
+@extend_schema_view(
+    get=extend_schema(operation_id='ListCorpusRoles', description='List all roles of a corpus'),
+    post=extend_schema(description='Create a new entity role')
+)
 class CorpusRoles(CorpusACLMixin, ListCreateAPIView):
     """
     List all roles in a corpus
@@ -77,6 +81,11 @@ class CorpusRoles(CorpusACLMixin, ListCreateAPIView):
 
 
 @extend_schema(tags=['entities'])
+@extend_schema_view(
+    patch=extend_schema(description='Partially update an entity'),
+    put=extend_schema(description='Update an entity'),
+    delete=extend_schema(description='Delete an entity')
+)
 class EntityDetails(ACLMixin, RetrieveUpdateDestroyAPIView):
     """
     Get all information about an entity

arkindex/images/api.py

@@ -101,6 +101,11 @@ class IIIFInformationCreate(CreateAPIView):
 
 
 @extend_schema(tags=['images'])
+@extend_schema_view(
+    get=extend_schema(description='Retrieve an image'),
+    patch=extend_schema(description="Update an image's status"),
+    put=extend_schema(description="Update an image's status")
+)
 class ImageRetrieve(RetrieveUpdateAPIView):
     """
     Get information about an image or trigger a check

arkindex/project/openapi/patch.yml

@@ -10,35 +10,8 @@
 # Spectacular docs:
 # https://drf-spectacular.readthedocs.io/en/latest/customization.html
 
-/api/v1/corpus/:
-  get:
-    description: List corpora with their access rights
-  post:
-    description: Create a new corpus
-/api/v1/corpus/{corpus}/elements/:
-  delete:
-    operationId: DestroyElements
-    description: Delete elements in bulk
-/api/v1/corpus/{id}/:
-  get:
-    description: Retrieve a single corpus
-  put:
-    description: Update a corpus
-  patch:
-    description: Partially update a corpus
-  delete:
-    description: >-
-      Delete a corpus. Requires the "admin" right on the corpus.
-
-      This triggers an asynchronous deletion of a corpus and returns a
-      response immediately; the actual deletion will become visible once
-      the process is completed.
 /api/v1/corpus/{id}/roles/:
-  get:
-    operationId: ListCorpusRoles
-    description: List all roles of a corpus
   post:
-    description: Create a new entity role
     responses:
       '400':
         description: An error occured while creating the role.
@@ -61,19 +34,8 @@
                   id: 55cd009d-cd4b-4ec2-a475-b060f98f9138
                   corpus:
                     - Role already exists in this corpus
-/api/v1/element/{id}/:
-  get:
-    description: Retrieve a single element's informations and metadata
-  patch:
-    description: Rename an element
-  put:
-    description: Rename an element
-  delete:
-    description: Delete an element
 /api/v1/elements/selection/:
   delete:
-    operationId: RemoveSelection
-    description: Remove a specific element or delete any selection
     requestBody:
       content:
         application/json:
@@ -84,8 +46,6 @@
                 type: string
       x-name: body
   post:
-    operationId: AddSelection
-    description: Add specific elements
     requestBody:
       content:
         application/json:
@@ -100,20 +60,6 @@
             required:
             - ids
       x-name: body
-/api/v1/element/{child}/parent/{parent}/:
-  post:
-    operationId: CreateElementParent
-    description: Link an element to a new parent
-  delete:
-    operationId: DestroyElementParent
-    description: Delete the relation between an element and one of its parents
-/api/v1/entity/{id}/:
-  delete:
-    description: Delete an entity
-  patch:
-    description: Partially update an entity
-  put:
-    description: Update an entity
 /api/v1/image/:
   post:
     responses:
@@ -142,28 +88,6 @@
                   hash:
                     - Image with this hash already exists
                   id: 3cc2e9e0-4172-44b1-8d65-bc3fffd076dc
-/api/v1/image/{id}/:
-  get:
-    description: Retrieve an image
-  put:
-    description: Update an image's status
-  patch:
-    description: Update an image's status
-/api/v1/imports/file/{id}/:
-  get:
-    description: Get an uploaded file's metadata
-  patch:
-    description: Update a datafile's status
-  put:
-    description: Update a datafile's status
-  delete:
-    description: Delete an uploaded file
-/api/v1/imports/repos/{id}/:
-  delete:
-    description: Delete a repository
-/api/v1/imports/{id}/:
-  delete:
-    description: Delete a data import. Cannot be used on currently running data imports.
 /api/v1/imports/transkribus/:
   post:
     responses:
@@ -182,9 +106,6 @@
                 summary: An error where the user is not a member of the collection.
                 value:
                   collection_id: User user@example.com is not a member of the collection 1
-/api/v1/oauth/credentials/{id}/:
-  delete:
-    description: Delete OAuth credentials. This may disable access to some Git repositories.
 /api/v1/oauth/providers/{provider}/signin/:
   get:
     responses:
@@ -199,46 +120,3 @@
                   format: uri
                   description: URL to the authorization endpoint.
                   readOnly: true
-/api/v1/metadata/{id}/:
-  get:
-    operationId: RetrieveMetaData
-    description: Retrieve an existing metadata
-  patch:
-    operationId: PartialUpdateMetaData
-    description: Partially update an existing metadata
-  put:
-    operationId: UpdateMetaData
-    description: Update an existing metadata
-  delete:
-    operationId: DestroyMetaData
-    description: Delete an existing metadata
-/api/v1/user/:
-  get:
-    description: Retrieve information about the authenticated user
-  patch:
-    description: Update a user's password. This action is not allowed to users without confirmed e-mails.
-  put:
-    description: Update a user's password. This action is not allowed to users without confirmed e-mails.
-  delete:
-    operationId: Logout
-    description: Log out from the API
-/api/v1/group/{id}/:
-  patch:
-    description: >-
-      Partially update details of a group.
-      Requires to have `admin` privileges on this group.
-  put:
-    description:  >-
-      Update details of a group.
-      Requires to have `admin` privileges on this group.
-  delete:
-    description: >-
-      Delete a group.
-      Requires to have `admin` privileges on this group.
-/api/v1/membership/{id}/:
-  patch:
-    description: Partially update a generic membership.
-  put:
-    description: Update a generic membership.
-  delete:
-    description: Delete a generic membership.

arkindex/users/api.py

@@ -92,6 +92,9 @@ class CredentialsList(ListAPIView):
 
 
 @extend_schema(tags=['oauth'])
+@extend_schema_view(
+    delete=extend_schema(description='Delete OAuth credentials. This may disable access to some Git repositories.')
+)
 class CredentialsRetrieve(RetrieveDestroyAPIView):
     """
     Retrieve OAuth credentials.
@@ -109,6 +112,12 @@ class CredentialsRetrieve(RetrieveDestroyAPIView):
 
 
 @extend_schema(tags=['users'])
+@extend_schema_view(
+    get=extend_schema(description='Retrieve information about the authenticated user'),
+    patch=extend_schema(description="Update a user's password. This action is not allowed to users without confirmed e-mails."),
+    put=extend_schema(description="Update a user's password. This action is not allowed to users without confirmed e-mails."),
+    delete=extend_schema(operation_id='Logout', description='Log out from the API')
+)
 class UserRetrieve(RetrieveUpdateDestroyAPIView):
     """
     Retrieve information about the authenticated user
@@ -525,6 +534,20 @@ class GroupsCreate(CreateAPIView):
 
 
 @extend_schema(tags=['users'])
+@extend_schema_view(
+    patch=extend_schema(
+        description='Partially update details of a group. '
+                    'Requires to have `admin` privileges on this group.'
+    ),
+    put=extend_schema(
+        description='Update details of a group. '
+                    'Requires to have `admin` privileges on this group.'
+    ),
+    delete=extend_schema(
+        description='Delete a group. '
+                    'Requires to have `admin` privileges on this group.'
+    )
+)
 class GroupDetails(RetrieveUpdateDestroyAPIView):
     """
     Retrieve details about a specific group
@@ -615,6 +638,17 @@ class UserMemberships(ListAPIView):
 
 
 @extend_schema(tags=['users'])
+@extend_schema_view(
+    patch=extend_schema(
+        description='Partially update a generic membership.'
+    ),
+    put=extend_schema(
+        description='Update a generic membership.'
+    ),
+    delete=extend_schema(
+        description='Delete a generic membership.'
+    )
+)
 class MembershipDetails(ACLMixin, RetrieveUpdateDestroyAPIView):
     """
     Retrieve details of a generic membership