diff --git a/persistence-service-v1/persistence-service-external-api-v2/src/main/resources/api/documine.yaml b/persistence-service-v1/persistence-service-external-api-v2/src/main/resources/api/documine.yaml index c17d0b2b1..c75a780a3 100644 --- a/persistence-service-v1/persistence-service-external-api-v2/src/main/resources/api/documine.yaml +++ b/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 - 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. + Retrieves a collection of dossier status definitions 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 - 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 - a specific dossier template. + Retrieves a collection of dossier attribute definitions associated with a specific dossier template. + + This endpoint is useful for clients needing to understand what attributes are expected or allowed + 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 - facilitates to define the content of the download package and to start the creation of it for all - 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. + This endpoint allows you to define the content and initiate the creation of a + download package for all files within a dossier. + + #### 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. 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 - facilitates to define the content of the download package and to start the creation of it for the - 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. + This endpoint allows you to define the content and initiate the creation of a + download package for a files of a dossier. + + #### 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. parameters: - $ref: '#/components/parameters/dossierTemplateId' - $ref: '#/components/parameters/dossierId' @@ -1024,7 +1049,7 @@ paths: - 3. Files summary: Bulk delete specific files within a dossier. (DELETE with body payload) description: | - This endpoint allows for the bulk deletion of specified files associated with a certain dossier. + This endpoint allows for the bulk deletion of specified files associated with a certain dossier. It provides the flexibility to perform either a soft-delete (by default) or a permanent deletion. A soft-deleted file remains restorable within the retention period set by the application (96h by default). In contrast, permanently @@ -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 - facilitates to define the content of the download package and to start the creation of it for - 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. + This endpoint allows you to define the content and initiate the creation of a + download package for specific files of a dossier. + + #### 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. 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 - 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. + Use this endpoint to retrieve the list of downloads for the current user. + + 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 - 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 - entity object. + > **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. + > + > Example: Even if `bcd22239-c3df-442f-a5a1-1664cba94dc6_2` is not a valid UUID it is still a valid identifier for an + > 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 - elevated to a privileged member to ensure full functionality. + > **Note:** The DocuMine application does not have an approval workflow. However, every member will be + > 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: diff --git a/persistence-service-v1/persistence-service-external-api-v2/src/main/resources/api/redactmanager.yaml b/persistence-service-v1/persistence-service-external-api-v2/src/main/resources/api/redactmanager.yaml index 75c6be471..95c6baf94 100644 --- a/persistence-service-v1/persistence-service-external-api-v2/src/main/resources/api/redactmanager.yaml +++ b/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 - 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. + Retrieves a collection of dossier status definitions 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 - 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 - a specific dossier template. + Retrieves a collection of dossier attribute definitions associated with a specific dossier template. + + This endpoint is useful for clients needing to understand what attributes are expected or allowed + 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 - facilitates to define the content of the download package and to start the creation of it for all - 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. + This endpoint allows you to define the content and initiate the creation of a + download package for all files within a dossier. + + #### Request - Note: The redacted file will be created for `APPROVED` files only. + * 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 - facilitates to define the content of the download package and to start the creation of it for the - 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. + This endpoint allows you to define the content and initiate the creation of a + download package for a files of a dossier. + + #### Request - Note: The redacted PDF will be created for `APPROVED` files only. + * 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 - facilitates to define the content of the download package and to start the creation of it for - 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. + This endpoint allows you to define the content and initiate the creation of a + download package for specific files of a dossier. + + #### Request - Note: The redacted PDF will be created for `APPROVED` files only. + * 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 - 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. + Use this endpoint to retrieve the list of downloads for the current user. + + 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 - 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 - entity object. + > **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. + > + > Example: Even if `bcd22239-c3df-442f-a5a1-1664cba94dc6_2` is not a valid UUID it is still a valid identifier for an + > entity object. entityRuleId: type: string description: An identifier that represents a specific rule associated with the entity.