fix(api-settings): Added all Settings API endpoints to API docs gener…

…ation ZMS-145 (#671) * added list registered settings api endpoint to api docs generation * Added Create or Update Setting api endpoint to api docs generation * added get setting value api endpoint to api docs generation
nodemailer · Apr 15, 2024 · 02a43c6 · 02a43c6
1 parent c846b66
commit 02a43c6
Showing 1 changed file with 128 additions and 27 deletions.
diff --git a/lib/api/settings.js b/lib/api/settings.js
@@ -3,20 +3,64 @@
 const Joi = require('joi');
 const tools = require('../tools');
 const roles = require('../roles');
-const { sessSchema, sessIPSchema } = require('../schemas');
+const { sessSchema, sessIPSchema, booleanSchema } = require('../schemas');
+const { successRes } = require('../schemas/response/general-schemas');
 
 // allow overriding the following consts using the key format `const:archive:time`
 
 module.exports = (db, server, settingsHandler) => {
     server.get(
-        { name: 'settings', path: '/settings' },
+        {
+            name: 'settings',
+            path: '/settings',
+            tags: ['Settings'],
+            summary: 'List registered Settings',
+            validationObjs: {
+                requestBody: {},
+                queryParams: {
+                    filter: Joi.string().empty('').trim().max(128).description('Optional partial match of the Setting key'),
+                    sess: sessSchema,
+                    ip: sessIPSchema
+                },
+                pathParams: {},
+                response: {
+                    200: {
+                        description: 'Success',
+                        model: Joi.object({
+                            success: successRes,
+                            filter: Joi.string().description('Partial match if requested'),
+                            settings: Joi.array()
+                                .items(
+                                    Joi.object({
+                                        key: Joi.string().required().description('Setting key'),
+                                        value: Joi.alternatives()
+                                            .try(Joi.string().description('Setting value'), Joi.number().description('Setting value'))
+                                            .required()
+                                            .description('Setting value'),
+                                        name: Joi.string().required().description('Setting name'),
+                                        description: Joi.string().required().description('Setting description'),
+                                        type: Joi.string().required().description('Value subtype'),
+                                        custom: booleanSchema.required().description('If true then the value is set')
+                                    })
+                                        .$_setFlag('objectName', 'GetSettingsResult')
+                                        .required()
+                                )
+                                .description('Setting listing')
+                                .required()
+                        })
+                    }
+                }
+            }
+        },
         tools.responseWrapper(async (req, res) => {
             res.charSet('utf-8');
 
-            const schema = Joi.object().keys({
-                filter: Joi.string().empty('').trim().max(128),
-                sess: sessSchema,
-                ip: sessIPSchema
+            const { pathParams, requestBody, queryParams } = req.route.spec.validationObjs;
+
+            const schema = Joi.object({
+                ...pathParams,
+                ...requestBody,
+                ...queryParams
             });
 
             const result = schema.validate(req.params, {
@@ -51,25 +95,53 @@ module.exports = (db, server, settingsHandler) => {
     );
 
     server.post(
-        '/settings/:key',
+        {
+            path: '/settings/:key',
+            tags: ['Settings'],
+            summary: 'Create or Update Setting',
+            description: 'Create a new or update an existing setting',
+            validationObjs: {
+                requestBody: {
+                    value: Joi.any()
+                        .when('key', {
+                            switch: settingsHandler.keys.map(entry => ({
+                                is: entry.key,
+                                then: entry.schema
+                            }))
+                        })
+                        .required()
+                        .description('Setting value'),
+                    sess: sessSchema,
+                    ip: sessIPSchema
+                },
+                queryParams: {},
+                pathParams: {
+                    key: Joi.string()
+                        .empty('')
+                        .valid(...settingsHandler.keys.map(entry => entry.key))
+                        .required()
+                        .description('Key of the Setting')
+                },
+                response: {
+                    200: {
+                        description: 'Success',
+                        model: Joi.object({
+                            success: successRes,
+                            key: Joi.string().required().description('Key of the Setting')
+                        })
+                    }
+                }
+            }
+        },
         tools.responseWrapper(async (req, res) => {
             res.charSet('utf-8');
 
-            const schema = Joi.object().keys({
-                key: Joi.string()
-                    .empty('')
-                    .valid(...settingsHandler.keys.map(entry => entry.key))
-                    .required(),
-                value: Joi.any()
-                    .when('key', {
-                        switch: settingsHandler.keys.map(entry => ({
-                            is: entry.key,
-                            then: entry.schema
-                        }))
-                    })
-                    .required(),
-                sess: sessSchema,
-                ip: sessIPSchema
+            const { pathParams, requestBody, queryParams } = req.route.spec.validationObjs;
+
+            const schema = Joi.object({
+                ...pathParams,
+                ...requestBody,
+                ...queryParams
             });
 
             const result = schema.validate(req.params, {
@@ -114,14 +186,43 @@ module.exports = (db, server, settingsHandler) => {
     );
 
     server.get(
-        '/settings/:key',
+        {
+            path: '/settings/:key',
+            tags: ['Settings'],
+            summary: 'Get Setting value',
+            validationObjs: {
+                requestBody: {},
+                queryParams: {
+                    sess: sessSchema,
+                    ip: sessIPSchema
+                },
+                pathParams: {
+                    key: Joi.string().empty('').max(128).required().description('Key of the Setting')
+                },
+                response: {
+                    200: {
+                        description: 'Success',
+                        model: Joi.object({
+                            success: successRes,
+                            key: Joi.string().required().description('Key of the Setting'),
+                            value: Joi.alternatives()
+                                .try(Joi.string().description('Setting value'), Joi.number().description('Setting value'))
+                                .description('Setting value'),
+                            error: Joi.string().description('Error if present').example('Key was not found')
+                        })
+                    }
+                }
+            }
+        },
         tools.responseWrapper(async (req, res) => {
             res.charSet('utf-8');
 
-            const schema = Joi.object().keys({
-                key: Joi.string().empty('').max(128).required(),
-                sess: sessSchema,
-                ip: sessIPSchema
+            const { pathParams, requestBody, queryParams } = req.route.spec.validationObjs;
+
+            const schema = Joi.object({
+                ...pathParams,
+                ...requestBody,
+                ...queryParams
             });
 
             const result = schema.validate(req.params, {