diff --git a/.gitignore b/.gitignore index 57b168b92..1f0c847c0 100644 --- a/.gitignore +++ b/.gitignore @@ -33,4 +33,4 @@ gradlew.bat gradle/ **/.gradle -**/build \ No newline at end of file +**/build diff --git a/README.md b/README.md new file mode 100644 index 000000000..ecee4d29c --- /dev/null +++ b/README.md @@ -0,0 +1,57 @@ +![badge](https://img.shields.io/badge/license-knecon-brightgreen) +## Description +*TODO* + +## Table of Contents +- [Installation](#installation) +- [Usage](#usage) +- [License](#license) +- [Tests](#tests) +- [API](#api) +## Installation +*TODO* + +## Usage +*TODO* + +## License +![badge](https://img.shields.io/badge/license-knecon-brightgreen)
+This application is covered by the proprietary knecon license. + +## Tests +*TODO* + +## API + +### Files + +The OpenAPI specifications for RedactManager and Documine are located here:
`./persistence-service-v1/persistence-service-external-api-v2/src/main/resources/api` + +The Redocly configuration file `redocly.yaml` is located in the root directory of the project. It contains the settings for linting the specifications and generating the API documentation. If you run the redocly commands from there, you do not need to specify the path to the configuration file. + +The Redocly files are located in the `redocly` directory: +* The `templates` directory contains the [Handlebars](https://handlebarsjs.com/) templates for RedactManager and Documine, respectively. +* The `build` directory is the default output directory for the generated API documentation. + +### Redocly Installation +Execute the following command to install the Redocly CLI. +```bash +npm install -g @redocly/cli@latest +``` + +### Redocly Linting +Execute the following commands in the root directory of the project to lint the OpenAPI specifications. + +Please refer to the Redocly documentation for detailed information on the linting rules. + +```bash +redocly lint redactmanager +redocly lint documine +``` + +### Redocly Docs Generation +Execute the following commands in the root directory of the project to generate the API documentation. +```bash +redocly build-docs redactmanager --output ./redocly/build/redactmanager.html +redocly build-docs documine --output ./redocly/build/documine.html +``` \ No newline at end of file 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 3232ec7ac..f59f18611 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 @@ -3,8 +3,12 @@ info: title: DocuMine API version: "1.0.0" description: | + # Introduction + The DocuMine API provides a comprehensive solution for managing resources such as dossiers and their associated files. Users can also retrieve components of files that have been processed and extracted by the system. + + # Authorization All endpoints are secured using OAuth2, with the "authorizationCode" being the general supported authorization flow. Obtain a JWT token for authentication and send it in the 'Authorization' header with the format `Bearer {JWT_TOKEN}`. @@ -12,12 +16,13 @@ info: Please also note that the `authorizationUrl` and `tokenUrl` in this specification contain `{workspaceId}` placeholders that must be replaced by your respective DocuMine workspace identifier. - Example Headers: + **Example Headers:** ```properties Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI... ``` license: name: knecon License + url: https://knecon.swiss/documine/license contact: name: knecon Service Desk email: support@documine.ai @@ -275,6 +280,7 @@ paths: $ref: '#/components/responses/500' /api/dossier-templates/{dossierTemplateId}/dossier-status-definitions: get: + operationId: getDossierStatusDefinitions summary: Returns the list of all existing dossier status definitions tags: - 1. Dossier Templates @@ -312,6 +318,7 @@ paths: $ref: '#/components/responses/500' /api/dossier-templates/{dossierTemplateId}/dossier-attribute-definitions: get: + operationId: getDossierAttributeDefinitions summary: Returns the list of all existing dossier attribute definitions tags: - 1. Dossier Templates @@ -349,6 +356,7 @@ paths: $ref: '#/components/responses/500' /api/dossier-templates/{dossierTemplateId}/file-attribute-definitions: get: + operationId: getFileAttributeDefinitions summary: Returns the list of all existing file attribute definitions tags: - 1. Dossier Templates @@ -473,7 +481,7 @@ paths: "500": $ref: '#/components/responses/500' - /api/dossier-templates/{dossierTemplateId}/component-mappings/{comonentMappingId}: + /api/dossier-templates/{dossierTemplateId}/component-mappings/{componentMappingId}: get: operationId: downloadMappingFile tags: @@ -630,7 +638,7 @@ paths: "500": $ref: '#/components/responses/500' get: - operationId: getComponents + operationId: getComponentDefinitions tags: - Component Definitions summary: Get all component definitions @@ -853,6 +861,7 @@ paths: $ref: '#/components/responses/500' /api/dossier-templates/{dossierTemplateId}/report-templates: get: + operationId: getReportTemplates summary: Returns the list of all available report templates tags: - 1. Dossier Templates @@ -1518,7 +1527,6 @@ paths: parameters: - $ref: '#/components/parameters/dossierTemplateId' - $ref: '#/components/parameters/dossierId' - - $ref: '#/components/parameters/fileId' - $ref: '#/components/parameters/includeComponentDetails' responses: "200": 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 b3c81b549..46eb65060 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 @@ -3,10 +3,14 @@ info: title: RedactManager API version: "4.1.0-draft" description: | + # Introduction + The RedactManager API provides a comprehensive solution for managing resources such as dossiers and their associated files. Users can also retrieve the results package for files that have been processed by the system and reviewed by the users. The results package can contain the optimized PDF file, the preview PDF, the redacted PDF and correlating redaction reports in different formats. + + # Authorization All endpoints are secured using OAuth2, with the "authorizationCode" being the general supported authorization flow. Obtain a JWT token for authentication and send it in the 'Authorization' header with the format `Bearer {JWT_TOKEN}`. @@ -14,12 +18,13 @@ info: Please also note that the `authorizationUrl` and `tokenUrl` in this specification contain `{workspaceId}` placeholders that must be replaced by your respective RedactManager workspace identifier. - Example Headers: + **Example Headers:** ```properties Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI... ``` license: name: knecon License + url: https://knecon.swiss/redactmanager/license contact: name: knecon Service Desk email: support@redactmanager.com @@ -115,6 +120,7 @@ paths: $ref: '#/components/responses/500' /api/dossier-templates/{dossierTemplateId}/dossier-status-definitions: get: + operationId: getDossierStatusDefinitions summary: Returns the list of all existing dossier status definitions tags: - 1. Dossier Templates @@ -152,6 +158,7 @@ paths: $ref: '#/components/responses/500' /api/dossier-templates/{dossierTemplateId}/dossier-attribute-definitions: get: + operationId: getDossierAttributeDefinitions summary: Returns the list of all existing dossier attribute definitions tags: - 1. Dossier Templates @@ -189,11 +196,12 @@ paths: $ref: '#/components/responses/500' /api/dossier-templates/{dossierTemplateId}/file-attribute-definitions: get: + operationId: getFileAttributeDefinitions summary: Returns the list of all existing file attribute definitions tags: - 1. Dossier Templates description: | - Retrieves a collection of file attribute definitions associated with a specific dossier template. Each file + Use this endpoint to retrieve a collection of file attribute definitions associated with a specific dossier template. Each file 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 files associated with a specific dossier template. @@ -221,6 +229,7 @@ paths: $ref: '#/components/responses/500' /api/dossier-templates/{dossierTemplateId}/report-templates: get: + operationId: getReportTemplates summary: Returns the list of all available report templates tags: - 1. Dossier Templates @@ -415,7 +424,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. @@ -1063,14 +1072,14 @@ components: responses: "400": content: - '*/*': + 'application/json': schema: $ref: '#/components/schemas/ErrorMessage' description: | The request was malformed or invalid. Double-check the request structure or parameters. "401": content: - '*/*': + 'application/json': schema: $ref: '#/components/schemas/ErrorMessage' description: | @@ -1078,21 +1087,21 @@ components: resource. This error can happen if the access token was revoked or has expired. "403": content: - '*/*': + 'application/json': schema: $ref: '#/components/schemas/ErrorMessage' description: | Forbidden. Your credentials are valid, but you do not have permission to access this resource. "404-dossier-template": content: - '*/*': + 'application/json': schema: $ref: '#/components/schemas/ErrorMessage' description: | Dossier template not found. This happens if the requested dossier template does not exist. "404-dossier": content: - '*/*': + 'application/json': schema: $ref: '#/components/schemas/ErrorMessage' description: | @@ -1102,7 +1111,7 @@ components: for a previously existing dossier only if it is actually deleted permanently. "404-file": content: - '*/*': + 'application/json': schema: $ref: '#/components/schemas/ErrorMessage' description: | @@ -1112,35 +1121,35 @@ components: only if the file is deleted permanently. "404-download": content: - '*/*': + 'application/json': schema: $ref: '#/components/schemas/ErrorMessage' description: | Download not found. This happens if the requested download does not exist for the current user. "404-user": content: - '*/*': + 'application/json': schema: $ref: '#/components/schemas/ErrorMessage' description: | User not found. This happens if the requested user does not exist. "409-dossier-conflict": content: - '*/*': + 'application/json': schema: $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. "429": content: - '*/*': + 'application/json': schema: $ref: '#/components/schemas/ErrorMessage' description: | Too many requests have been made in a given time frame. Rate limiting is in place to prevent abuse. "500": content: - '*/*': + 'application/json': schema: $ref: '#/components/schemas/ErrorMessage' description: Internal Server Error. An unexpected error occurred on the server side. Please try again later or contact support. @@ -1154,18 +1163,6 @@ 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 @@ -1404,37 +1401,6 @@ components: If the `username` parameter is set, the user list is filtered for that specific user name. This means the list either has one matching entry or is empty. schemas: - EntityReference: - type: object - description: | - Represents a reference to an entity object discovered in a document. Together with the unique identifier - of the entity, the reference contains some basic details of the entity. - properties: - id: - type: string - 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 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. - type: - type: string - description: The name of the entity. - page: - type: integer - format: int32 - description: The page number in the document where the entity is located. - example: - id: bcd22239-cedf-442f-a5a1-1664cba94dc6 - entityRuleId: ABC.0.0 - type: entity_type - page: 123 DossierStatusDefinition: type: object description: | diff --git a/redocly.yaml b/redocly.yaml new file mode 100644 index 000000000..6151b8d1e --- /dev/null +++ b/redocly.yaml @@ -0,0 +1,35 @@ +extends: + - recommended + +apis: + redactmanager: + root: ./persistence-service-v1/persistence-service-external-api-v2/src/main/resources/api/redactmanager.yaml + labels: + - redactmanager + theme: + openapi: + htmlTemplate: ./redocly/templates/redactmanager.hbs + generateCodeSamples: + languages: + - lang: curl + label: Script (cURL) + - lang: Python + - lang: JavaScript + hideRequestPayloadSample: false + disableSearch: false + + documine: + root: ./persistence-service-v1/persistence-service-external-api-v2/src/main/resources/api/documine.yaml + labels: + - documine + theme: + openapi: + htmlTemplate: ./redocly/templates/documine.hbs + generateCodeSamples: + languages: + - lang: curl + label: Script (cURL) + - lang: Python + - lang: JavaScript + hideRequestPayloadSample: false + disableSearch: false diff --git a/redocly/templates/documine.hbs b/redocly/templates/documine.hbs new file mode 100644 index 000000000..2fb2719ee --- /dev/null +++ b/redocly/templates/documine.hbs @@ -0,0 +1,18 @@ + + + + {{title}} + + + + + + {{{redocHead}}} + {{#unless disableGoogleFont}}{{/unless}} + + +
{{{redocHTML}}}
+ + \ No newline at end of file diff --git a/redocly/templates/redactmanager.hbs b/redocly/templates/redactmanager.hbs new file mode 100644 index 000000000..a1164bd9a --- /dev/null +++ b/redocly/templates/redactmanager.hbs @@ -0,0 +1,18 @@ + + + + {{title}} + + + + + + {{{redocHead}}} + {{#unless disableGoogleFont}}{{/unless}} + + +
{{{redocHTML}}}
+ + \ No newline at end of file