RedactManager API Specs for BASF - Improved descriptions

persistence-service-v1/persistence-service-external-api-v2/src/main/resources/api/documine.yaml

@@ -279,9 +279,15 @@ paths:
       tags:
         - 1. Dossier Templates
       description: |
-        Retrieves a collection of dossier status definitions associated with a specific dossier template. Each dossier
+        Retrieves a collection of dossier status definitions associated with a specific dossier template.
-        status definition includes details such as the status name, description, and other relevant metadata. This endpoint 
+        
-        is useful for clients needing to display or set the status of a dossier associated with a specific dossier template.
+        This endpoint is useful for clients needing to display or set the status of a dossier associated
+        with a specific dossier template.
+        
+        #### Response
+        
+        Each dossier status definition includes details such as the status name, description, and other 
+        relevant metadata.
       parameters:
         - $ref: '#/components/parameters/dossierTemplateId'
       responses:
@@ -310,10 +316,15 @@ paths:
       tags:
         - 1. Dossier Templates
       description: |
-        Retrieves a collection of dossier attribute definitions associated with a specific dossier template. Each dossier
+        Retrieves a collection of dossier attribute definitions associated with a specific dossier template.
-        attribute definition includes details such as attribute type, name, and other relevant metadata. This endpoint 
+        
-        is useful for clients needing to understand what attributes are expected or allowed for dossiers associated with 
+        This endpoint is useful for clients needing to understand what attributes are expected or allowed
-        a specific dossier template.
+        for dossiers associated with a specific dossier template.
+        
+        #### Response
+        
+        Each dossier attribute definition includes details such as attribute type, name, and other relevant
+        metadata.
       parameters:
         - $ref: '#/components/parameters/dossierTemplateId'
       responses:
@@ -741,7 +752,7 @@ paths:
         - 2. Dossiers
       summary: Update or set attributes for a specific dossier.
       description: |
-        This endpoint facilitates the updating or setting of specific dossier attributes for a given dossier. 
+        Use this endpoint to update or set dossier attributes for a given dossier. 
         Ensure you provide the necessary dossier attributes within the request body.
 
         Use this route to maintain or enhance dossier metadata and properties.
@@ -777,11 +788,18 @@ paths:
         - 2. Dossiers
       summary: Initiate the creation of a download package for all files of a dossier.
       description: |
-        To download files and reports, a download package needs to be prepared. This endpoint
+        This endpoint allows you to define the content and initiate the creation of a
-        facilitates to define the content of the download package and to start the creation of it for all
+        download package for all files within a dossier.
-        files of the dossier. The response of this endpoint contains an identifier for the download that
+
-        is needed to query the status until the download package is prepared, and finally to actually 
+        #### Request
-        download the file once it is available.
+
+        * Specify the files and reports to be included in the download package.
+        * Start the process of creating the download package.
+
+        #### Response
+
+        Includes an identifier for the download. Use this identifier to query the status
+        of the download package preparation and download the file once it is available.
       parameters:
         - $ref: '#/components/parameters/dossierTemplateId'
         - $ref: '#/components/parameters/dossierId'
@@ -858,7 +876,7 @@ paths:
         - 3. Files
       summary: Upload a file and associate it with a specific dossier.
       description: |
-        This endpoint facilitates the upload of files to a specific dossier.
+        Use this endpoint to upload files to a specific dossier.
         
         Upon successful upload, the system returns the unique identifier of the uploaded file. In cases where the dossier already 
         contains a file with the same name, the new file will replace the existing one.
@@ -916,7 +934,7 @@ paths:
         - 3. Files
       summary: Deletes a specific file associated with a dossier and its template.
       description: |
-        This endpoint facilitates the removal of a file linked to a specific dossier under a dossier template. By default, the
+        Use this endpoint to remove of a file linked to a specific dossier under a dossier template. By default, the
         file undergoes a soft-delete, meaning it can be restored within the retention period determined by application settings.
         The default retention period is 96 hours (4 days) but may vary based on configuration. Use the `deletePermanently` query
         parameter to opt for a permanent deletion, preventing any future restoration.
@@ -982,11 +1000,18 @@ paths:
         - 3. Files
       summary: Initiate the creation of a download package for a single file of a dossier.
       description: |
-        To download files and reports, a download package needs to be prepared. This endpoint
+        This endpoint allows you to define the content and initiate the creation of a 
-        facilitates to define the content of the download package and to start the creation of it for the
+        download package for a files of a dossier.
-        file. The response of this endpoint contains an identifier for the download that is needed to
+
-        query the status until the download package is prepared for download, and finally to actually 
+        #### Request
-        download the file once it is available.
+        
+        * Specify the files and reports to be included in the download package.
+        * Start the process of creating the download package.
+
+        #### Response
+
+        Includes an identifier for the download. Use this identifier to query the status
+        of the download package preparation and download the file once it is available.
       parameters:
         - $ref: '#/components/parameters/dossierTemplateId'
         - $ref: '#/components/parameters/dossierId'
@@ -1064,11 +1089,18 @@ paths:
         - 3. Files
       summary: Initiate the creation of a download package for specific files within a dossier.
       description: |
-        To download files and reports, a download package needs to be prepared. This endpoint
+        This endpoint allows you to define the content and initiate the creation of a 
-        facilitates to define the content of the download package and to start the creation of it for
+        download package for specific files of a dossier.
-        multiple files of a dossier. The response of this endpoint contains an identifier for the download
+
-        that is needed to query the status until the download package is prepared for download, and finally
+        #### Request
-        to actually download the file once it is available.
+        
+        * Specify the files and reports to be included in the download package.
+        * Start the process of creating the download package.
+
+        #### Response
+
+        Includes an identifier for the download. Use this identifier to query the status
+        of the download package preparation and download the file once it is available.
       parameters:
         - $ref: '#/components/parameters/dossierTemplateId'
         - $ref: '#/components/parameters/dossierId'
@@ -1105,7 +1137,7 @@ paths:
         - 3. Files
       summary: Update or set attributes for a specific file.
       description: |
-        This endpoint facilitates the updating or setting of specific file attributes for a given file within a dossier. 
+        Use this endpoint to update or setting of specific file attributes for a given file within a dossier. 
         Ensure you provide the necessary file attributes within the request body.
         
         Use this route to maintain or enhance file metadata and properties.
@@ -1180,9 +1212,9 @@ paths:
       operationId: getComponentsOfDossier
       tags:
         - 4. Components
-      summary: Returns the RSS response for all files of a dossier
+      summary: Returns the FileComponents of all files in a dossier
       description: |
-        This endpoint fetches components for all files associated with a specified dossier. Like individual file components, 
+        This endpoint fetches components for all files associated with a specific dossier. Like individual file components, 
         these represent various aspects, metadata or content of the files. Entity and component rules define these components based on the file's
         content. They can give a *structured view* on a document's text.
         
@@ -1222,9 +1254,12 @@ paths:
         - 5. Downloads
       summary: Get the list of downloads for the current user
       description: |
-        This endpoint facilitates to retrieve the list of downloads for the current user. The response contains 
+        Use this endpoint to retrieve the list of downloads for the current user.
-        status objects that represent each download and provide information on whether the download is still 
+        
-        in preparation, is already available or whether an error occurred when the download package was created.
+        The response contains the status of each download.
+        
+        A download may be queued, generating, finished or failed. When it is finished, the
+        download package may be obtained using the download endpoint
       responses:
         "200":
           content:
@@ -1249,7 +1284,7 @@ paths:
         - 5. Downloads
       summary: Get the status for a specific download of the current user
       description: |
-        This endpoint facilitates to retrieve the status for a specific download. In addition to other 
+        Use this endpoint to retrieve the status for a specific download. In addition to other 
         information, the status indicates whether the download is still being prepared, is already 
         available, or whether an error occurred when the download package was created.
       parameters:
@@ -1279,7 +1314,7 @@ paths:
         - 5. Downloads
       summary: Deletes a specific download.
       description: |
-        This endpoint facilitates the removal of a download.
+        Use this endpoint to remove a download.
       parameters:
         - $ref: '#/components/parameters/downloadId'
       responses:
@@ -1306,7 +1341,7 @@ paths:
         - persistence-service
       summary: Download the download package.
       description: |
-        This endpoint facilitates to actually download the created download package. The request will
+        Use this endpoint to actually download the created download package. The request will
         only be successful if the status of the download is `READY`.
       parameters:
         - $ref: '#/components/parameters/downloadId'
@@ -1343,7 +1378,7 @@ paths:
         - tenant-user-management
       summary: Get a list of users
       description: |
-        This endpoint facilitates to retrieve a list of known users.
+        Use this endpoint to retrieve a list of known users.
         
         With the `username` parameter you can filter for a specific user name. If the parameter is 
         used, the returned list either contains a single matching entry or is empty.
@@ -1373,7 +1408,7 @@ paths:
         - 6. Users
       summary: Retrieve a specific user by its identifier.
       description: |
-        This endpoint facilitates to retrieve a specific user.
+        Use this endpointUse this endpoint to retrieve a specific user.
       responses:
         "200":
           content:
@@ -1746,7 +1781,7 @@ components:
       
         Using this parameter, you can also permanently delete a previously soft-deleted dossier during its retention period.
         
-        Note: Deleting a dossier also deletes all associated files.
+        > **Note:** Deleting a dossier also deletes all associated files.
     permanentlyDeleteFile:
       name: deletePermanently
       in: query
@@ -1849,11 +1884,11 @@ components:
           description: |
             The unique identifier for the entity.
             
-            Note: In general, it is a valid UUID. Only if an entity spans over multiple pages, it is split on page breaks. Each
+            > **Note:** In general, it is a valid UUID. Only if an entity spans over multiple pages, it is split on page breaks. Each
-            part becomes an own entity object and the first one keeps the UUID while the following get an additional suffix.
+            > part becomes an own entity object and the first one keeps the UUID while the following get an additional suffix.
-            
+            > 
-            Example: Even is `bcd22239-c3df-442f-a5a1-1664cba94dc6_2` is not a valid UUID it is still a valid identifier for an
+            > Example: Even if `bcd22239-c3df-442f-a5a1-1664cba94dc6_2` is not a valid UUID it is still a valid identifier for an
-            entity object.
+            > entity object.
         entityRuleId:
           type: string
           description: An identifier that represents a specific rule associated with the entity.
@@ -2508,8 +2543,8 @@ components:
           description: |
             List of unique user identifiers with elevated permissions. Needed if using an approval workflow.
             
-            The DocuMine application does not have an approval workflow. However, every member will be
+            > **Note:** The DocuMine application does not have an approval workflow. However, every member will be
-            elevated to a privileged member to ensure full functionality.
+            > elevated to a privileged member to ensure full functionality.
         visibility:
           type: string
           enum:
@@ -2538,13 +2573,13 @@ components:
           format: uuid
           deprecated: true
           description: |
-            In DocuMine, watermarks are not supported.
+            > **Note:** In DocuMine, watermarks are not supported.
         previewWatermarkId:
           type: string
           format: uuid
           deprecated: true
           description: |
-            In DocuMine, watermarks are not supported.
+            > **Note:** In DocuMine, watermarks are not supported.
         dossierAttributes:
           $ref: '#/components/schemas/DossierAttributes'
         downloadFileTypes:

persistence-service-v1/persistence-service-external-api-v2/src/main/resources/api/redactmanager.yaml

@@ -119,9 +119,15 @@ paths:
       tags:
         - 1. Dossier Templates
       description: |
-        Retrieves a collection of dossier status definitions associated with a specific dossier template. Each dossier
+        Retrieves a collection of dossier status definitions associated with a specific dossier template.
-        status definition includes details such as the status name, description, and other relevant metadata. This endpoint 
+        
-        is useful for clients needing to display or set the status of a dossier associated with a specific dossier template.
+        This endpoint is useful for clients needing to display or set the status of a dossier associated
+        with a specific dossier template.
+        
+        #### Response
+        
+        Each dossier status definition includes details such as the status name, description, and other 
+        relevant metadata.
       parameters:
         - $ref: '#/components/parameters/dossierTemplateId'
       responses:
@@ -150,10 +156,15 @@ paths:
       tags:
         - 1. Dossier Templates
       description: |
-        Retrieves a collection of dossier attribute definitions associated with a specific dossier template. Each dossier
+        Retrieves a collection of dossier attribute definitions associated with a specific dossier template.
-        attribute definition includes details such as attribute type, name, and other relevant metadata. This endpoint 
+        
-        is useful for clients needing to understand what attributes are expected or allowed for dossiers associated with 
+        This endpoint is useful for clients needing to understand what attributes are expected or allowed
-        a specific dossier template.
+        for dossiers associated with a specific dossier template.
+        
+        #### Response
+        
+        Each dossier attribute definition includes details such as attribute type, name, and other relevant
+        metadata.
       parameters:
         - $ref: '#/components/parameters/dossierTemplateId'
       responses:
@@ -409,13 +420,20 @@ paths:
         - 2. Dossiers
       summary: Initiate the creation of a download package for all files of a dossier.
       description: |
-        To download the results of a redaction, a download package needs to be prepared. This endpoint
+        This endpoint allows you to define the content and initiate the creation of a 
-        facilitates to define the content of the download package and to start the creation of it for all
+        download package for all files within a dossier.
-        files of the dossier. The response of this endpoint contains an identifier for the download that
-        is needed to query the status until the download package is prepared, and finally to actually 
-        download the file once it is available.
 
-        Note: The redacted file will be created for `APPROVED` files only.
+        #### Request
+        
+        * Specify the files and reports to be included in the download package.
+        * Start the process of creating the download package.
+
+        #### Response
+
+        Includes an identifier for the download. Use this identifier to query the status
+        of the download package preparation and download the file once it is available.
+        
+        > **Note:** The redacted file will be created for `APPROVED` files only.
       parameters:
         - $ref: '#/components/parameters/dossierTemplateId'
         - $ref: '#/components/parameters/dossierId'
@@ -492,7 +510,7 @@ paths:
         - 3. Files
       summary: Upload a file and associate it with a specific dossier.
       description: |
-        This endpoint facilitates the upload of files to a specific dossier.
+        Use this endpoint to upload files to a specific dossier.
         
         Upon successful upload, the system returns the unique identifier of the uploaded file. In cases where the dossier already 
         contains a file with the same name, the new file will replace the existing one.
@@ -550,7 +568,7 @@ paths:
         - 3. Files
       summary: Deletes a specific file associated with a dossier and its template.
       description: |
-        This endpoint facilitates the removal of a file linked to a specific dossier under a dossier template. By default, the
+        Use this endpoint to remove of a file linked to a specific dossier under a dossier template. By default, the
         file undergoes a soft-delete, meaning it can be restored within the retention period determined by application settings.
         The default retention period is 96 hours (4 days) but may vary based on configuration. Use the `deletePermanently` query
         parameter to opt for a permanent deletion, preventing any future restoration.
@@ -616,13 +634,20 @@ paths:
         - 3. Files
       summary: Initiate the creation of a download package for a single file of a dossier.
       description: |
-        To download the results of a redaction, a download package needs to be prepared. This endpoint
+        This endpoint allows you to define the content and initiate the creation of a 
-        facilitates to define the content of the download package and to start the creation of it for the
+        download package for a files of a dossier.
-        file. The response of this endpoint contains an identifier for the download that is needed to
-        query the status until the download package is prepared for download, and finally to actually 
-        download the file once it is available.
 
-        Note: The redacted PDF will be created for `APPROVED` files only.
+        #### Request
+        
+        * Specify the files and reports to be included in the download package.
+        * Start the process of creating the download package.
+
+        #### Response
+
+        Includes an identifier for the download. Use this identifier to query the status
+        of the download package preparation and download the file once it is available.
+        
+        > **Note:** The redacted file will be created for `APPROVED` files only.
       parameters:
         - $ref: '#/components/parameters/dossierTemplateId'
         - $ref: '#/components/parameters/dossierId'
@@ -700,13 +725,20 @@ paths:
         - 3. Files
       summary: Initiate the creation of a download package for specific files within a dossier.
       description: |
-        To download the results of a redaction, a download package needs to be prepared. This endpoint
+        This endpoint allows you to define the content and initiate the creation of a 
-        facilitates to define the content of the download package and to start the creation of it for
+        download package for specific files of a dossier.
-        multiple files of a dossier. The response of this endpoint contains an identifier for the download
-        that is needed to query the status until the download package is prepared for download, and finally
-        to actually download the file once it is available.
 
-        Note: The redacted PDF will be created for `APPROVED` files only.
+        #### Request
+        
+        * Specify the files and reports to be included in the download package.
+        * Start the process of creating the download package.
+
+        #### Response
+
+        Includes an identifier for the download. Use this identifier to query the status
+        of the download package preparation and download the file once it is available.
+        
+        > **Note:** The redacted file will be created for `APPROVED` files only.
       parameters:
         - $ref: '#/components/parameters/dossierTemplateId'
         - $ref: '#/components/parameters/dossierId'
@@ -743,7 +775,7 @@ paths:
         - 3. Files
       summary: Update or set attributes for a specific file.
       description: |
-        This endpoint facilitates the updating or setting of specific file attributes for a given file within a dossier. 
+        Use this endpoint to update or setting of specific file attributes for a given file within a dossier. 
         Ensure you provide the necessary file attributes within the request body.
         
         Use this route to maintain or enhance file metadata and properties.
@@ -780,9 +812,12 @@ paths:
         - 5. Downloads
       summary: Get the list of downloads for the current user
       description: |
-        This endpoint facilitates to retrieve the list of downloads for the current user. The response contains 
+        Use this endpoint to retrieve the list of downloads for the current user.
-        status objects that represent each download and provide information on whether the download is still 
+        
-        in preparation, is already available or whether an error occurred when the download package was created.
+        The response contains the status of each download.
+        
+        A download may be queued, generating, finished or failed. When it is finished, the
+        download package may be obtained using the download endpoint
       responses:
         "200":
           content:
@@ -807,7 +842,7 @@ paths:
         - 5. Downloads
       summary: Get the status for a specific download of the current user
       description: |
-        This endpoint facilitates to retrieve the status for a specific download. In addition to other 
+        Use this endpoint to retrieve the status for a specific download. In addition to other 
         information, the status indicates whether the download is still being prepared, is already 
         available, or whether an error occurred when the download package was created.
       parameters:
@@ -837,7 +872,7 @@ paths:
         - 5. Downloads
       summary: Deletes a specific download.
       description: |
-        This endpoint facilitates the removal of a download.
+        Use this endpoint to remove a download.
       parameters:
         - $ref: '#/components/parameters/downloadId'
       responses:
@@ -864,7 +899,7 @@ paths:
         - persistence-service
       summary: Download the download package.
       description: |
-        This endpoint facilitates to actually download the created download package. The request will
+        Use this endpoint to actually download the created download package. The request will
         only be successful if the status of the download is `READY`.
       parameters:
         - $ref: '#/components/parameters/downloadId'
@@ -901,7 +936,7 @@ paths:
         - tenant-user-management
       summary: Get a list of users
       description: |
-        This endpoint facilitates to retrieve a list of known users.
+        Use this endpoint to retrieve a list of known users.
         
         With the `username` parameter you can filter for a specific user name. If the parameter is 
         used, the returned list either contains a single matching entry or is empty.
@@ -931,7 +966,7 @@ paths:
         - 6. Users
       summary: Retrieve a specific user by its identifier.
       description: |
-        This endpoint facilitates to retrieve a specific user.
+        Use this endpointUse this endpoint to retrieve a specific user.
       responses:
         "200":
           content:
@@ -1246,7 +1281,7 @@ components:
       
         Using this parameter, you can also permanently delete a previously soft-deleted dossier during its retention period.
         
-        Note: Deleting a dossier also deletes all associated files.
+        > **Note:** Deleting a dossier also deletes all associated files.
     permanentlyDeleteFile:
       name: deletePermanently
       in: query
@@ -1335,11 +1370,11 @@ components:
           description: |
             The unique identifier for the entity.
             
-            Note: In general, it is a valid UUID. Only if an entity spans over multiple pages, it is split on page breaks. Each
+            > **Note:** In general, it is a valid UUID. Only if an entity spans over multiple pages, it is split on page breaks. Each
-            part becomes an own entity object and the first one keeps the UUID while the following get an additional suffix.
+            > part becomes an own entity object and the first one keeps the UUID while the following get an additional suffix.
-            
+            > 
-            Example: Even is `bcd22239-c3df-442f-a5a1-1664cba94dc6_2` is not a valid UUID it is still a valid identifier for an
+            > Example: Even if `bcd22239-c3df-442f-a5a1-1664cba94dc6_2` is not a valid UUID it is still a valid identifier for an
-            entity object.
+            > entity object.
         entityRuleId:
           type: string
           description: An identifier that represents a specific rule associated with the entity.