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 2c7b10965..e2444103e 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 @@ -297,7 +297,17 @@ paths: - 1. Dossier Templates summary: Returns a list of all existing component mappings in a dossier template description: | - Retrieves a collection of component mapping views associated with a specific dossier template. Each component mapping view includes details such as name, number of lines, delimiter, encoding and other relevant metadata. This endpoint is useful for clients needing to understand what mappings are available under a particular dossier template. + Use this endpoint to retrieve a summary of all component mappings associated with a specific DossierTemplate. + + The summary includes: + - Name + - Column Labels + - Number of lines + - Delimiter + - Encoding + of each component mapping. + + This endpoint is useful for clients to understand the available mappings under a particular DossierTemplate. parameters: - $ref: '#/components/parameters/dossierTemplateId' responses: @@ -324,12 +334,23 @@ paths: operationId: uploadMapping summary: Upload a new component mapping to a DossierTemplate. description: | - Utilize this endpoint to upload a new component mapping to a designated DossierTemplate. - The file is expected to be a comma separated file, whose first row are the labels for the columns of the file. - Further, it is expected that the data is rectangular, this means each row has the same size. - The rows in the file will be sorted the values in each column, starting with the left most and moving right recursively. - This enables much faster lookups down the line. - This means, it is highly beneficial to structure the CSV File such that the keys to query for appear in the first rows and the results to map in the last. + Use this endpoint to upload a new component mapping to a specific DossierTemplate. + + - **File Format:** CSV (comma-separated values). + - **Header:** The first row should contain column labels. + - **Data Structure:** Ensure all rows have the same number of columns (rectangular data). + - **Sorting:** Rows will be sorted by the values in each column, from left to right, for faster lookups. + - **Customization:** Users can specify the delimiter and encoding of the CSV file. + - **Usage** The component mapping file can be used in component rules to relate components to existing master data. + + **Tip:** Place keys to be queried in the first columns and results to be mapped in the last column for best performance. + + Example: + | search_value | mapped_value | + | ------------ | ------------ | + | Alice | Manager | + | Bob | Developer | + | Charlie | Analyst | tags: - 1. Dossier Templates requestBody: @@ -347,7 +368,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ComponentMappingMetadata' + $ref: '#/components/schemas/ComponentMapping' description: | Component mapping uploaded successfully and returned the component mapping metadata. "400": @@ -370,9 +391,10 @@ paths: - 1. Dossier Templates summary: Download a specific component mapping file of a specific dossier template. description: | - Utilize this endpoint to download a specific component mapping file of a designated dossier template. - The file is named the same and encoded the same as when it was uploaded, but it's sorting might have changed to provide faster lookups. - A component mapping file may be used in the component rules to relate components to existing master data. + Use this endpoint to download a specific component mapping file of a designated DossierTemplate. + + - The file retains its original name and encoding as when it was uploaded. + - The sorting of the file may have changed to enable faster lookups. parameters: - $ref: '#/components/parameters/dossierTemplateId' - $ref: '#/components/parameters/componentMappingId' @@ -404,7 +426,24 @@ paths: put: operationId: updateMapping summary: Update an existing component mapping of a DossierTemplate. - description: Updates an existing component mapping, + description: | + Use this endpoint to update an existing component mapping of a specific dossier template. + + - **File Format:** CSV (comma-separated values). + - **Header:** The first row should contain column labels. + - **Data Structure:** Ensure all rows have the same number of columns (rectangular data). + - **Sorting:** Rows will be sorted by the values in each column, from left to right, for faster lookups. + - **Customization:** Users can specify the delimiter and encoding of the CSV file. + - **Usage** The component mapping file can be used in component rules to relate components to existing master data. + + **Tip:** Place keys to be queried in the first columns and results to be mapped in the last column for best performance. + + Example: + | search_value | mapped_value | + | ------------ | ------------ | + | Alice | Manager | + | Bob | Developer | + | Charlie | Analyst | tags: - 1. Dossier Templates requestBody: @@ -422,7 +461,7 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/ComponentMappingMetadata' + $ref: '#/components/schemas/ComponentMapping' description: | Component mapping uploaded successfully and returned the component mapping metadata. "400": @@ -1090,7 +1129,9 @@ components: - UTF_16LE - ISO-8859-1 - US-ASCII - description: "An identifier for the used encoding of the file. Only java's standard charsets are supported, default value is 'UTF-8'" + example: UTF-8 + default: UTF-8 + description: "An identifier for the used encoding of the file. Only java's standard charsets are supported." delimiter: name: delimiter required: false @@ -1100,7 +1141,8 @@ components: minLength: 1 maxLength: 1 example: ',' - description: "The delimiter used as a separator in a csv file. Default is ','." + default: ',' + description: "The delimiter used as a separator in a csv file." mappingName: name: name required: false @@ -2070,7 +2112,7 @@ components: - 8130acf6-4910-4123-827c-caacd8111402 dossierStatusId: b8280985-f558-43c0-852a-a3fa86803548 - ComponentMappingMetadata: + ComponentMapping: description: | The `ComponentMappingMetadata` object represents the metadata of a component mapping csv file. These CSV files may be used in the component rules to relate components to an existing knowledge base. type: object @@ -2168,7 +2210,7 @@ components: A list of component mapping metadata associated with this dossier template. type: array items: - $ref: "#/components/schemas/ComponentMappingMetadata" + $ref: "#/components/schemas/ComponentMapping" required: - dossierTemplateId - ComponentMappingSummary