@manyos/smileconnect-api 1.71.8 → 1.72.1

package/conf/clients.json

@@ -2693,7 +2693,38 @@
       },
       "scriptEndpoints": {
         "personData": {
-          "options": {},
+          "options": {
+            "openAPISpec": {
+              "summary": "Bla bla",
+              "decription": "Bla bla bla bla bla",
+              "requestSchema": {
+                "type": "object",
+                "properties": {
+                  "loginid": {
+                    "type": "string",
+                    "maxLength": 15,
+                    "description": "Login ID"
+                  }
+                },
+                "required": [
+                  "loginid"
+                ]
+              },
+              "responseSchema": {
+                "type": "object",
+                "properties": {
+                  "approver": {
+                    "type": "string",
+                    "description": "Approver username"
+                  }
+                },
+                "required": [
+                  "approver"
+                ]
+              },
+              "description": "Run scripts associated with this endpoint"
+            }
+          },
           "scripts": [
             "script1_env",
             "script1"
@@ -2702,4 +2733,4 @@
       }
     }
   }
-]
+]

package/docs/releases.md

@@ -1,6 +1,9 @@
 # Release Notes
 
 ## API
+### 1.72.1 - 13.11.25
+Improve OpenAPI Documentation generation. Add requestBody for POST and put requests. Allow custom definition for scriptendpoints.
+
 ### 1.71.8 - 22.10.25
 Fix error when include classAttributes was used in CI Search
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@manyos/smileconnect-api",
-  "version": "1.71.8",
+  "version": "1.72.1",
   "description": "A proxy and abstraction layer for BMCs IT Service Management Suite",
   "main": "app.js",
   "scripts": {

package/util/config.js

@@ -11,6 +11,8 @@ const mappingUtil = require('../util/mappingUtil');
 const CacheService = require ('../util/cache.service');
 
 const CONSTANTS = require('./constants');
+const {response} = require("express");
+const {get} = require("mongoose");
 
 const configFileCustomFormMapping = 'conf/customFormMapping.json';
 
@@ -321,6 +323,35 @@ function checkClientConfig(client) {
         updateRequired = true;
     }
 
+    const scriptEnpointKeys = Object.keys(clientConfig.scriptEndpoints);
+    scriptEnpointKeys.forEach(scriptEnpointKey => {
+        const scriptEnpointConfig = clientConfig.scriptEndpoints[scriptEnpointKey];
+        if (!scriptEnpointConfig.options) {
+            scriptEnpointConfig.options = {};
+            updateRequired = true;
+        }
+        if (!scriptEnpointConfig.options.openAPISpec) {
+            scriptEnpointConfig.options.openAPISpec = {};
+            updateRequired = true;
+        }
+        if (!scriptEnpointConfig.options.openAPISpec.summary) {
+            scriptEnpointConfig.options.openAPISpec.summary = "Run scripts associated with this endpoint";
+            updateRequired = true;
+        }
+        if (!scriptEnpointConfig.options.openAPISpec.description) {
+            scriptEnpointConfig.options.openAPISpec.description = "Run scripts associated with this endpoint";
+            updateRequired = true;
+        }
+        if (!scriptEnpointConfig.options.openAPISpec.requestSchema) {
+            scriptEnpointConfig.options.openAPISpec.requestSchema = {};
+            updateRequired = true;
+        }
+        if (!scriptEnpointConfig.options.openAPISpec.responseSchema) {
+            scriptEnpointConfig.options.openAPISpec.responseSchema = {};
+            updateRequired = true;
+        }
+    });
+
     if (clientConfig.options.translateSelectionFields === undefined) {
         clientConfig.options.translateSelectionFields = true;
         updateRequired = true;
@@ -396,11 +427,13 @@ async function getDesignPackage(clientId) {
             if (clientObjectConfig.fields && clientObjectConfig.fields.length > 0){
                 const mapping = getDeprecatedMappingAsCustom(config.requestType)
                 schemas[config.requestType] = await getObjectSchema(clientObjectConfig.fields, mapping, config.forms.regular)
+                schemas[config.requestType+'_create_update'] = await getObjectSchema(clientObjectConfig.fields, mapping, config.forms.regular, true)
                 paths = {...paths, ... await getPathDef(config.assocTicketType, config.baseURI, config.requestType)}
             }
             if (config.requestTypeWorkLog && clientConfig[config.requestTypeWorkLog].fields && clientConfig[config.requestTypeWorkLog].fields.length > 0) {
                 const mapping = getDeprecatedMappingAsCustom(config.requestTypeWorkLog)
                 schemas[config.requestTypeWorkLog] = await getObjectSchema(clientConfig[config.requestTypeWorkLog].fields, mapping, config.forms.workLog)
+                schemas[config.requestTypeWorkLog + '_create_update'] = await getObjectSchema(clientConfig[config.requestTypeWorkLog].fields, mapping, config.forms.workLog, true)
                 paths = {...paths, ... await getPathDef(config.assocTicketType, config.baseURI + '/{ticketId}/worklogs', config.requestTypeWorkLog, true, true)}
             }
             if (config.requestTemplate && clientConfig[config.requestTemplate].fields  && clientConfig[config.requestTemplate].fields.length > 0) {
@@ -454,7 +487,8 @@ async function getDesignPackage(clientId) {
         const clientObjectConfig = clientConfig[`custom_${formName}`]
         log.debug('key', key, clientObjectConfig)
         if (clientObjectConfig) {
-            schemas[key] = await getObjectSchema(clientObjectConfig.fields, customFormMappings[key].mapping, formName)
+            schemas[key] = await getObjectSchema(clientObjectConfig.fields, customFormMappings[key].mapping, formName);
+            schemas[key+'_create_update'] = await getObjectSchema(clientObjectConfig.fields, customFormMappings[key].mapping, formName, true);
             paths = {...paths, ... await getPathDef(key, '/v1/customForms/' + key, key)}
         }
     }
@@ -465,18 +499,21 @@ async function getDesignPackage(clientId) {
         const scriptKeys = Object.keys(clientConfig.scriptEndpoints)
         for (let x=0; x < scriptKeys.length; x++) {
             const key = scriptKeys[x]
+            const endpointConfig = clientConfig.scriptEndpoints[key];
+            const openAPISpec = endpointConfig.options.openAPISpec;
             log.debug('key', key)
-            //schemas[key] = await getObjectSchema(clientObjectConfig.fields, customFormMappings[key].mapping, formName)
             const pathDef = {}
             pathDef[`/v1/scriptEndpoints/${key}`] = {};
             pathDef[`/v1/scriptEndpoints/${key}`].post = {
                 tags: [key],
-                summary: `Run scripts associated with this endpoint`,
-                description: "Run scripts associated that are associated with this endpoint. The return Schema is defined in the scripts.",
+                summary: openAPISpec.summary || `Run scripts associated with this endpoint`,
+                description: openAPISpec.decription || "Run scripts associated that are associated with this endpoint. The return Schema is defined in the scripts.",
                 parameters: [],
-                responses: await getApiResponse("scriptEndpoint_" + key, true)
+                responses: await getApiResponse("scriptEndpoint_" + key, true),
+                requestBody: await getApiRequestBody("scriptEndpoint_" + key)
             }
-            schemas["scriptEndpoint_" + key] = {};
+            schemas["scriptEndpoint_" + key] = openAPISpec.responseSchema || {};
+            schemas["scriptEndpoint_" + key + '_create_update'] = openAPISpec.requestSchema || {};
             paths = {...paths, ... pathDef}
         }
     }
@@ -486,6 +523,7 @@ async function getDesignPackage(clientId) {
 
     if (clientConfig.cmdbobject && clientConfig.cmdbobject.fields) {
         schemas['cmdbobject'] = await getObjectSchema(clientConfig.cmdbobject.fields, cmdbMapping, 'AST:BaseElement')
+        schemas['cmdbobject_create_update'] = await getObjectSchema(clientConfig.cmdbobject.fields, cmdbMapping, 'AST:BaseElement', true)
 
 
         const cmdbdef = Object.keys(clientConfig.cmdbobject)
@@ -505,6 +543,10 @@ async function getDesignPackage(clientId) {
                 required: schemas['cmdbobject'].required.concat(classSchema.required),
                 properties: {...schemas['cmdbobject'].properties, ...classSchema.properties}
             }
+            schemas[`${schemaName}_create_update`] = {
+                required: schemas['cmdbobject'].required.concat(classSchema.required),
+                properties: {...schemas['cmdbobject'].properties, ...classSchema.properties}
+            }
             log.debug('customForm', formName, fields, classMapping, classSchema)
         }
 
@@ -551,7 +593,7 @@ async function getPathDef(objectName, baseUri, schema, isSubTicket, suppressUpda
             tags: tag,
             summary: `Get a single ${objectName} object by id`,
             description: "A single object is returned in the data attribute",
-            parameters: [],
+            parameters: getOpenApiParameters('get'),
             responses: await getApiResponse(schema, true)
         }
     }
@@ -560,8 +602,9 @@ async function getPathDef(objectName, baseUri, schema, isSubTicket, suppressUpda
             tags: tag,
                 summary: `Update an object of type ${objectName}`,
                 description: "A single object is returned in the data attribute",
-                parameters: [],
-                responses: await getApiResponse(schema, true)
+                parameters: getOpenApiParameters('put'),
+                responses: await getApiResponse(schema, true),
+                requestBody: await getApiRequestBody(schema)
         }
     }
 
@@ -570,7 +613,7 @@ async function getPathDef(objectName, baseUri, schema, isSubTicket, suppressUpda
             tags: tag,
             summary: `Get a list of object of type ${objectName}`,
             description: "An array ob objects is returned in the data attribute",
-            parameters: [],
+            parameters: getOpenApiParameters('getAll'),
             responses: await getApiResponse(schema, false)
         }
     }
@@ -579,8 +622,9 @@ async function getPathDef(objectName, baseUri, schema, isSubTicket, suppressUpda
             tags: tag,
             summary: `Create a new object of type ${objectName}`,
             description: "A single object is returned in the data attribute",
-            parameters: [],
-            responses: await getApiResponse(schema, false)
+            parameters: getOpenApiParameters('post'),
+            responses: await getApiResponse(schema, false),
+            requestBody: await getApiRequestBody(schema)
         }
     }
     if (isSubTicket) {
@@ -589,6 +633,43 @@ async function getPathDef(objectName, baseUri, schema, isSubTicket, suppressUpda
     return pathDef
 }
 
+function getOpenApiParameters(operation) {
+    const parameters = [
+        {
+            "examples": {
+                "sample": {
+                    "value": "user123"
+                }
+            },
+            "name": "impersonateUser",
+            "description": "If the clientConfig has the option allowDynamicImpersonate set to *true* then the URL Parameter *impersonateUser* can be used to determine the used Remedy User.",
+            "schema": {
+                "type": "string"
+            },
+            "in": "query",
+            "required": false
+        },
+        {
+            "examples": {
+                "include": {
+                    "value": "ciRelations,ticketRelations"
+                }
+            },
+            "name": "include",
+            "description": "Defines if and which related objects shoudl be included.\nPossible values:\nciRelations,ticketRelations,personRelations,organisationRelations,supportGroupRelations,persons,supportGroups,organisations,cmdbObjects,incidents,workOrders,changes, problems",
+            "schema": {
+                "type": "array",
+                "items": {
+                    "type": "string"
+                }
+            },
+            "in": "query",
+            "required": false
+        }
+    ]
+    return parameters;
+}
+
 async function getApiResponse(schema, single) {
     let dataValue = {
         "$ref": `#/components/schemas/${schema}`
@@ -628,7 +709,35 @@ async function getApiResponse(schema, single) {
     return responses
 }
 
-async function getObjectSchema(clientFields, mapping, formName) {
+async function getApiRequestBody(schema) {
+    let dataValue = {
+        "$ref": `#/components/schemas/${schema}_create_update`
+    }
+    if (Array.isArray(schema)) {
+        dataValue = {
+            oneOf: schema.map(item => {
+                return {
+                    "$ref": `#/components/schemas/${item}_create_update`
+                }
+            })
+        }
+    }
+    return requestBody = {
+            content: {
+                "application/json": {
+                    schema: {
+                        type: "object",
+                        properties: {
+                            data: dataValue
+                        }
+                    }
+                }
+            },
+            required: true
+        }
+}
+
+async function getObjectSchema(clientFields, mapping, formName, isCreateUpdate = false) {
     const fields = await getFields(formName)
     const required = []
     const properties = {}
@@ -638,37 +747,40 @@ async function getObjectSchema(clientFields, mapping, formName) {
         const fieldDef = {}
         const fieldDetails = fields.find(item => item.name === field)
 
-        if (fieldDetails) {
-            fieldDef.type = fieldDetails.type
-            if (fieldDetails.entryMode === 'Required') {
-                required.push(mappedName)
-            }
-            if(fieldDetails.fieldLimit) {
-                fieldDef.maxLength = fieldDetails.fieldLimit.maxLength
-            }
-            if (fieldDetails.type === 'SelectionField') {
-                fieldDef.type = 'string'
-                if (fieldDetails.fieldLimit && fieldDetails.fieldLimit.values) {
-                    const enumVals = fieldDetails.fieldLimit.values.map(item => item.enumItemName)
-                    fieldDef.enum = enumVals
-                } else if (fieldDetails.fieldLimit && fieldDetails.fieldLimit.valueMapping) {
-                    const enumVals = Object.values(fieldDetails.fieldLimit.valueMapping)
-                    fieldDef.enum = enumVals
+        // remove id field from create/update schema
+        if (!isCreateUpdate || mappedName !== 'id') {
+            if (fieldDetails) {
+                fieldDef.type = fieldDetails.type
+                if (fieldDetails.entryMode === 'Required') {
+                    required.push(mappedName)
                 }
+                if(fieldDetails.fieldLimit) {
+                    fieldDef.maxLength = fieldDetails.fieldLimit.maxLength
+                }
+                if (fieldDetails.type === 'SelectionField') {
+                    fieldDef.type = 'string'
+                    if (fieldDetails.fieldLimit && fieldDetails.fieldLimit.values) {
+                        const enumVals = fieldDetails.fieldLimit.values.map(item => item.enumItemName)
+                        fieldDef.enum = enumVals
+                    } else if (fieldDetails.fieldLimit && fieldDetails.fieldLimit.valueMapping) {
+                        const enumVals = Object.values(fieldDetails.fieldLimit.valueMapping)
+                        fieldDef.enum = enumVals
+                    }
 
-            } else if (fieldDetails.type === 'CharacterField') {
-                fieldDef.type = 'string'
-            } else if (fieldDetails.type === 'DateTimeField') {
-                fieldDef.type = 'string'
-                fieldDef.format = 'date-time'
-            } else if (fieldDetails.type === 'DateField') {
-                fieldDef.format = 'date'
-            } else if (fieldDetails.type === 'DecimalField') {
-                fieldDef.type = 'number'
+                } else if (fieldDetails.type === 'CharacterField') {
+                    fieldDef.type = 'string'
+                } else if (fieldDetails.type === 'DateTimeField') {
+                    fieldDef.type = 'string'
+                    fieldDef.format = 'date-time'
+                } else if (fieldDetails.type === 'DateField') {
+                    fieldDef.format = 'date'
+                } else if (fieldDetails.type === 'DecimalField') {
+                    fieldDef.type = 'number'
+                }
+                //fieldDef.details = fieldDetails
             }
-            //fieldDef.details = fieldDetails
+            properties[mappedName] = fieldDef
         }
-        properties[mappedName] = fieldDef
     })
     //mappedFields.push(fields)
     return {required, properties}