RED-7962 Added rule upload and download specification to openapi.yaml

Other changes:
* minor renamings
* fixed query parameter name to camelCase
* changed response code for invalid rules to 422 (unprocessable entity)
* changed filename of rules to lower case

persistence-service-v1/persistence-service-external-api-impl-v2/src/main/java/com/iqser/red/persistence/service/v2/external/api/impl/controller/DossierTemplateControllerV2.java

@@ -49,7 +49,7 @@ import lombok.SneakyThrows;
 @Tag(name = "1. Dossier templates endpoints", description = "Provides operations related to dossier templates")
 public class DossierTemplateControllerV2 implements DossierTemplateResource {
 
-    private static final String RULES_DOWNLOAD_FILE_NAME = "rules.drl";
+    private static final String RULES_DOWNLOAD_FILE_NAME_SUFFIX = "-rules.drl";
 
     private final DossierTemplateController dossierTemplateController;
     private final RulesPersistenceService rulesPersistenceService;
@@ -123,7 +123,7 @@ public class DossierTemplateControllerV2 implements DossierTemplateResource {
                         .toList();
 
                 // TODO Add warning and deprecations to response
-                return new ResponseEntity<>(RulesValidationResponse.builder().errors(rulesSyntaxErrorMessages).build(), HttpStatus.BAD_REQUEST);
+                return new ResponseEntity<>(RulesValidationResponse.builder().errors(rulesSyntaxErrorMessages).build(), HttpStatus.UNPROCESSABLE_ENTITY);
             }
         } catch (FeignException e) {
             if (e.status() == HttpStatus.BAD_REQUEST.value()) {
@@ -156,7 +156,7 @@ public class DossierTemplateControllerV2 implements DossierTemplateResource {
         HttpHeaders httpHeaders = new HttpHeaders();
         httpHeaders.setContentType(MediaType.APPLICATION_OCTET_STREAM);
 
-        httpHeaders.add("Content-Disposition", "attachment" + "; filename*=utf-8''" + StringEncodingUtils.urlEncode(ruleFileType.name() + "_" + RULES_DOWNLOAD_FILE_NAME));
+        httpHeaders.add("Content-Disposition", "attachment" + "; filename*=utf-8''" + StringEncodingUtils.urlEncode(ruleFileType.name().toLowerCase() + RULES_DOWNLOAD_FILE_NAME_SUFFIX));
 
         InputStream is = new ByteArrayInputStream(data);
 

persistence-service-v1/persistence-service-external-api-v2/src/main/java/com/iqser/red/service/persistence/service/v2/api/external/resource/DossierTemplateResource.java

@@ -39,7 +39,7 @@ public interface DossierTemplateResource {
 
     String RULE_FILE_TYPE_PARAMETER_NAME = "ruleFileType";
 
-    String DRY_RUN_PARAM = "dry-run";
+    String DRY_RUN_PARAM = "dryRun";
 
 
     @GetMapping(value = PATH, produces = MediaType.APPLICATION_JSON_VALUE)

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

@@ -108,6 +108,170 @@ paths:
           $ref: '#/components/responses/429'
         "500":
           $ref: '#/components/responses/500'
+  /api/dossier-templates/{dossierTemplateId}/entity-rules:
+    get:
+      operationId: downloadEntityRules
+      tags:
+        - 1. Dossier Templates
+      summary: Download the entity rules of a specific dossier template.
+      description: |
+        Utilize this endpoint to download the entity rules of a designated dossier template. The file is named 'entity-rules.drl'
+        and contains the set of rules to annotate the entities in an analyzed file. The content of this file is in the Drools Rule Language
+        (DRL) format. Please find more details about the DRL in the 
+        [Drools Language Reference](https://docs.drools.org/8.44.0.Final/drools-docs/drools/language-reference/index.html).
+      parameters:
+        - $ref: '#/components/parameters/dossierTemplateId'
+      responses:
+        "200":
+          headers:
+            Content-Disposition:
+              schema:
+                type: string
+                example: attachment; filename*=utf-8''entity-rules.drl
+          content:
+            application/octet-stream:
+              schema:
+                type: string
+                format: binary
+          description: |
+            Successfully downloaded the requested rules file.
+        "400":
+          $ref: '#/components/responses/400'
+        "401":
+          $ref: '#/components/responses/401'
+        "403":
+          $ref: '#/components/responses/403'
+        "404":
+          $ref: '#/components/responses/404-dossier-template'
+        "429":
+          $ref: '#/components/responses/429'
+        "500":
+          $ref: '#/components/responses/500'
+    post:
+      operationId: uploadEntityRules
+      tags:
+        - 1. Dossier Templates
+      summary: Upload or validate a entity rules file for a specific dossier template.
+      description: |
+        Utilize this endpoint to upload the entity rules to a designated dossier template. With the 'dryRun' parameter,
+        you have the possibility to just validate the rules file without actually saving it in the dossier template.
+        
+        The uploaded rule file will be saved only if 'dryRun' is set to `false` and the response code is `200`. In this
+        case, the response object does not contain errors.
+      parameters:
+        - $ref: '#/components/parameters/dossierTemplateId'
+        - $ref: '#/components/parameters/dryRun'
+      requestBody:
+        content:
+          multipart/form-data:
+            schema:
+              $ref: '#/components/schemas/UploadRequest'
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RuleValidation'
+              example:
+                errors: [ ]
+          description: |
+            Successfully uploaded or validated the entity rules file. The returned response object will not contain any errors.
+        "400":
+          $ref: '#/components/responses/400'
+        "401":
+          $ref: '#/components/responses/401'
+        "403":
+          $ref: '#/components/responses/403'
+        "404":
+          $ref: '#/components/responses/404-dossier'
+        "422":
+          $ref: '#/components/responses/422-rules'
+        "429":
+          $ref: '#/components/responses/429'
+        "500":
+          $ref: '#/components/responses/500'
+  /api/dossier-templates/{dossierTemplateId}/component-rules:
+    get:
+      operationId: downloadComponentRules
+      tags:
+        - 1. Dossier Templates
+      summary: Download the component rules of a specific dossier template.
+      description: |
+        Utilize this endpoint to download the component rules of a designated dossier template. The file is named 'component-rules.drl'
+        and contains the set of rules to build components based on entities of an analyzed file. The content of this file is in the Drools Rule Language
+        (DRL) format. Please find more details about the DRL in the 
+        [Drools Language Reference](https://docs.drools.org/8.44.0.Final/drools-docs/drools/language-reference/index.html).
+      parameters:
+        - $ref: '#/components/parameters/dossierTemplateId'
+      responses:
+        "200":
+          headers:
+            Content-Disposition:
+              schema:
+                type: string
+                example: attachment; filename*=utf-8''component-rules.drl
+          content:
+            application/octet-stream:
+              schema:
+                type: string
+                format: binary
+          description: |
+            Successfully downloaded the requested rules file.
+        "400":
+          $ref: '#/components/responses/400'
+        "401":
+          $ref: '#/components/responses/401'
+        "403":
+          $ref: '#/components/responses/403'
+        "404":
+          $ref: '#/components/responses/404-dossier-template'
+        "429":
+          $ref: '#/components/responses/429'
+        "500":
+          $ref: '#/components/responses/500'
+    post:
+      operationId: uploadComponentRules
+      tags:
+        - 1. Dossier Templates
+      summary: Upload or validate a component rules file for a specific dossier template.
+      description: |
+        Utilize this endpoint to upload the component rules to a designated dossier template. With the 'dryRun' parameter,
+        you have the possibility to just validate the rules file without actually saving it in the dossier template.
+        
+        The uploaded rule file will be saved only if 'dryRun' is set to `false` and the response code is `200`. In this
+        case, the response object does not contain errors.
+      parameters:
+        - $ref: '#/components/parameters/dossierTemplateId'
+        - $ref: '#/components/parameters/dryRun'
+      requestBody:
+        content:
+          multipart/form-data:
+            schema:
+              $ref: '#/components/schemas/UploadRequest'
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RuleValidation'
+              example:
+                errors: [ ]
+          description: |
+            Successfully uploaded or validated the component rules file. The returned response object will not contain any errors.
+        "400":
+          $ref: '#/components/responses/400'
+        "401":
+          $ref: '#/components/responses/401'
+        "403":
+          $ref: '#/components/responses/403'
+        "404":
+          $ref: '#/components/responses/404-dossier'
+        "422":
+          $ref: '#/components/responses/422-rules'
+        "429":
+          $ref: '#/components/responses/429'
+        "500":
+          $ref: '#/components/responses/500'
   /api/dossier-templates/{dossierTemplateId}/dossiers:
     get:
       operationId: getDossiers
@@ -664,6 +828,13 @@ components:
             $ref: '#/components/schemas/ErrorMessage'
       description: |
         Name conflict: The provided name is already in use by another dossier. It needs to be unique in the scope of your workspace.
+    422-rules:
+      content:
+        '*/*':
+          schema:
+            $ref: '#/components/schemas/RuleValidation'
+      description: |
+        Invalid rules file: There were validation errors, the rules file is unprocessable.
     "429":
       content:
         '*/*':
@@ -687,6 +858,18 @@ components:
       style: simple
       explode: false
       description: The identifier of a dossier template
+    dryRun:
+      name: dryRun
+      in: query
+      required: false
+      schema:
+        default: false
+        type: boolean
+      style: form
+      explode: true
+      description: |
+        A toggle to activate the dry-run mode: If set to `false` (default), the request will update the system. 
+        If set to `true`, the request will just be evaluated without actual changes in the system.
     dossierId:
       name: dossierId
       in: path
@@ -1681,7 +1864,7 @@ components:
           description: A detailed description of the error, providing insights on the problem and potentially how to resolve or avoid it.
       example:
         timestamp: "2023-09-21T12:45:00Z"
-        message: "Invalid input provided for the 'name' field."
+        message: "An error occurred while processing the request."
     FileAttributes:
       type: object
       description: Additional file attributes that can be set or imported
@@ -2202,6 +2385,43 @@ components:
             type: string
           type: array
       type: object
+    RuleValidationMessage:
+      description: Object containing information about an uploaded rules file.
+      example:
+        line: 123
+        column: 45
+        message: "Unable to Analyse Expression ..."
+      properties:
+        line:
+          description: The line number where the error or warning occurs.
+          format: int32
+          type: integer
+        column:
+          description: The column number where the error or warning occurs.
+          format: int32
+          type: integer
+        message:
+          description: The error or warning message that describes the details.
+          type: string
+      type: object
+    RuleValidation:
+      description: |
+        Information about the uploaded rules file. The `error` field is empty if there were no validation errors in the uploaded rules file.
+      example:
+        errors:
+          - line: 123
+            column: 45
+            message: "Unable to Analyse Expression ..."
+          - line: 234
+            column: 5
+            message: "Invalid rule syntax ..."
+      properties:
+        errors:
+          description: List of errors found in the uploaded rules file.
+          items:
+            $ref: '#/components/schemas/RuleValidationMessage'
+          type: array
+      type: object
     LicenseReport:
       type: object
       description: A comprehensive report of licensing metrics and usage statistics.