Marmelator/persistence-service
1
0
Fork 0
Code Issues Pull Requests 17 Actions Packages Projects Releases 1.1k Wiki Activity

Fixed some errors in the API specification.

Browse Source 
Additionally, added configuration and template files for Redocly API linting and docs generation, and added instructions how to use Redocly CLI.
This commit is contained in:
Kresnadi Budisantoso 2024-09-10 17:48:23 +02:00
parent 979e6a6650
commit 635dc05bde
7 changed files with 164 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.gitignore vendored
View File

@ -33,4 +33,4 @@ gradlew.bat
gradle/
**/.gradle
**/build
**/build

57
README.md Normal file
View File

@ -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)<br />
This application is covered by the proprietary knecon license.
## Tests
*TODO*
## API
### Files
The OpenAPI specifications for RedactManager and Documine are located here:<br> `./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
```

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

@ -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":

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

@ -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: |

35
redocly.yaml Normal file
View File

@ -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

18
redocly/templates/documine.hbs Normal file
View File

@ -0,0 +1,18 @@
<html>
<head>
<meta charset='utf8' />
<title>{{title}}</title>
<!-- needed for adaptive design -->
<meta description='{{{templateOptions.metaDescription}}}' />
<meta name='viewport' content='width=device-width, initial-scale=1' />
<link href="https://app.documine.ai/ui/assets/icons/documine-logo.ico" id="favicon" rel="icon" type="image/x-icon">
<style>
body { padding: 0; margin: 0; }
</style>
{{{redocHead}}}
{{#unless disableGoogleFont}}<link href='https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700' rel='stylesheet' />{{/unless}}
</head>
<body>
<div id='redoc-container'>{{{redocHTML}}}</div>
</body>
</html>

18
redocly/templates/redactmanager.hbs Normal file
View File

@ -0,0 +1,18 @@
<html>
<head>
<meta charset='utf8' />
<title>{{title}}</title>
<!-- needed for adaptive design -->
<meta description='{{{templateOptions.metaDescription}}}' />
<meta name='viewport' content='width=device-width, initial-scale=1' />
<link href="https://app.redactmanager.com/ui/favicon.ico" id="favicon" rel="icon" type="image/x-icon">
<style>
body { padding: 0; margin: 0; }
</style>
{{{redocHead}}}
{{#unless disableGoogleFont}}<link href='https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700' rel='stylesheet' />{{/unless}}
</head>
<body>
<div id='redoc-container'>{{{redocHTML}}}</div>
</body>
</html>