From e5636452a19217fc10598dd1f728b19a1fa50b7a Mon Sep 17 00:00:00 2001 From: Kresnadi Budisantoso Date: Thu, 23 Nov 2023 15:33:17 +0100 Subject: [PATCH] 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 --- .../DossierTemplateControllerV2.java | 6 +- .../resource/DossierTemplateResource.java | 2 +- .../src/main/resources/api/openapi.yaml | 222 +++++++++++++++++- 3 files changed, 225 insertions(+), 5 deletions(-) diff --git a/persistence-service-v1/persistence-service-external-api-impl-v2/src/main/java/com/iqser/red/persistence/service/v2/external/api/impl/controller/DossierTemplateControllerV2.java b/persistence-service-v1/persistence-service-external-api-impl-v2/src/main/java/com/iqser/red/persistence/service/v2/external/api/impl/controller/DossierTemplateControllerV2.java index 2dea6931a..1376d1d60 100644 --- a/persistence-service-v1/persistence-service-external-api-impl-v2/src/main/java/com/iqser/red/persistence/service/v2/external/api/impl/controller/DossierTemplateControllerV2.java +++ b/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); diff --git a/persistence-service-v1/persistence-service-external-api-v2/src/main/java/com/iqser/red/service/persistence/service/v2/api/external/resource/DossierTemplateResource.java b/persistence-service-v1/persistence-service-external-api-v2/src/main/java/com/iqser/red/service/persistence/service/v2/api/external/resource/DossierTemplateResource.java index 3c30b6671..e2dbdb738 100644 --- a/persistence-service-v1/persistence-service-external-api-v2/src/main/java/com/iqser/red/service/persistence/service/v2/api/external/resource/DossierTemplateResource.java +++ b/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) diff --git a/persistence-service-v1/persistence-service-external-api-v2/src/main/resources/api/openapi.yaml b/persistence-service-v1/persistence-service-external-api-v2/src/main/resources/api/openapi.yaml index a4b42ba64..b13f5f3f5 100644 --- a/persistence-service-v1/persistence-service-external-api-v2/src/main/resources/api/openapi.yaml +++ b/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.