fix(api-webhooks): added all webhook api endpoints to api docs generation ZMS-153 (#686)

* Added submission api endpoint to api docs generation

* added Delete a webhook api endpoint to api docs generation

* added Create new Webhook api endpoint to api docs generation

* Added List registered webhooks api endpoint to api docs generation

Author: NickOvt

lib/api/webhooks.js

@@ -6,22 +6,66 @@ const ObjectId = require('mongodb').ObjectId;
 const tools = require('../tools');
 const roles = require('../roles');
 const { nextPageCursorSchema, previousPageCursorSchema, pageNrSchema, sessSchema, sessIPSchema } = require('../schemas');
+const { successRes, totalRes, pageRes, previousCursorRes, nextCursorRes } = require('../schemas/response/general-schemas');
 
 module.exports = (db, server) => {
     server.get(
-        { name: 'webhooks', path: '/webhooks' },
+        {
+            name: 'webhooks',
+            path: '/webhooks',
+            tags: ['Webhooks'],
+            summary: 'List registered Webhooks',
+            validationObjs: {
+                requestBody: {},
+                queryParams: {
+                    type: Joi.string()
+                        .empty('')
+                        .lowercase()
+                        .max(128)
+                        .description('Prefix or exact match. Prefix match must end with ".*", eg "channel.*". Use "*" for all types'),
+                    user: Joi.string().hex().lowercase().length(24).description('User ID'),
+                    limit: Joi.number().default(20).min(1).max(250).description('How many records to return'),
+                    next: nextPageCursorSchema,
+                    previous: previousPageCursorSchema,
+                    page: pageNrSchema,
+                    sess: sessSchema,
+                    ip: sessIPSchema
+                },
+                pathParams: {},
+                response: {
+                    200: {
+                        description: 'Success',
+                        model: Joi.object({
+                            success: successRes,
+                            total: totalRes,
+                            page: pageRes,
+                            previousCursor: previousCursorRes,
+                            nextCursor: nextCursorRes,
+                            results: Joi.array()
+                                .items(
+                                    Joi.object({
+                                        id: Joi.string().required().description('Webhooks unique ID (24 byte hex)'),
+                                        type: Joi.array().items(Joi.string()).required().description('An array of event types this webhook matches'),
+                                        user: Joi.string().required().description('User ID or null'),
+                                        url: Joi.string().required().description('Webhook URL')
+                                    }).$_setFlag('objectName', 'GetWebhooksResult')
+                                )
+                                .required()
+                                .description('Webhook listing')
+                        })
+                    }
+                }
+            }
+        },
         tools.responseWrapper(async (req, res) => {
             res.charSet('utf-8');
 
-            const schema = Joi.object().keys({
-                type: Joi.string().empty('').lowercase().max(128),
-                user: Joi.string().hex().lowercase().length(24),
-                limit: Joi.number().default(20).min(1).max(250),
-                next: nextPageCursorSchema,
-                previous: previousPageCursorSchema,
-                page: pageNrSchema,
-                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, {
@@ -137,18 +181,46 @@ module.exports = (db, server) => {
     );
 
     server.post(
-        '/webhooks',
+        {
+            path: '/webhooks',
+            tags: ['Webhooks'],
+            summary: 'Create new Webhook',
+            validationObjs: {
+                requestBody: {
+                    type: Joi.array()
+                        .items(Joi.string().trim().max(128).lowercase())
+                        .required()
+                        .description('An array of event types to match. For prefix match use ".*" at the end (eg. "user.*") or "*" for all types'),
+                    user: Joi.string().hex().lowercase().length(24).description('User ID to match (only makes sense for user specific resources)'),
+                    url: Joi.string()
+                        .uri({ scheme: [/smtps?/, /https?/], allowRelative: false, relativeOnly: false })
+                        .required()
+                        .description('URL to POST data to'),
+                    sess: sessSchema,
+                    ip: sessIPSchema
+                },
+                queryParams: {},
+                pathParams: {},
+                response: {
+                    200: {
+                        description: 'Success',
+                        model: Joi.object({
+                            success: successRes,
+                            id: Joi.string().required().description('ID of the Webhook')
+                        })
+                    }
+                }
+            }
+        },
         tools.responseWrapper(async (req, res) => {
             res.charSet('utf-8');
 
-            const schema = Joi.object().keys({
-                type: Joi.array().items(Joi.string().trim().max(128).lowercase()).required(),
-                user: Joi.string().hex().lowercase().length(24),
-                url: Joi.string()
-                    .uri({ scheme: [/smtps?/, /https?/], allowRelative: false, relativeOnly: false })
-                    .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, {
@@ -240,14 +312,34 @@ module.exports = (db, server) => {
     );
 
     server.del(
-        '/webhooks/:webhook',
+        {
+            path: '/webhooks/:webhook',
+            tags: ['Webhooks'],
+            summary: 'Delete a webhook',
+            validationObjs: {
+                requestBody: {},
+                queryParams: {
+                    sess: sessSchema,
+                    ip: sessIPSchema
+                },
+                pathParams: { webhook: Joi.string().hex().lowercase().length(24).required().description('ID of the Webhook') },
+                response: {
+                    200: {
+                        description: 'Success',
+                        model: Joi.object({ success: successRes })
+                    }
+                }
+            }
+        },
         tools.responseWrapper(async (req, res) => {
             res.charSet('utf-8');
 
-            const schema = Joi.object().keys({
-                webhook: Joi.string().hex().lowercase().length(24).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, {