fix(api-domainaliases): Added DomainAliases API endpoints to API docs…

… generation ZMS-132 (#641) * added List registered Domain Aliases endpoint to API docs generation * added Create new Domain Alias API endpoint to API docs generation * added Resolve ID for a domain alias API endpoint to API docs generation * added Delete an Alias API endpoint to API docs generation * Added Request Alias information API endpoint to API docs generation
nodemailer · Mar 7, 2024 · 5af8126 · 5af8126
1 parent 64c6b5e
commit 5af8126
Showing 1 changed file with 162 additions and 35 deletions.
diff --git a/lib/api/domainaliases.js b/lib/api/domainaliases.js
@@ -7,21 +7,60 @@ const tools = require('../tools');
 const roles = require('../roles');
 const { nextPageCursorSchema, previousPageCursorSchema, pageNrSchema, sessSchema, sessIPSchema } = require('../schemas');
 const { publish, DOMAINALIAS_CREATED, DOMAINALIAS_DELETED } = require('../events');
+const { successRes, totalRes, pageRes, previousCursorRes, nextCursorRes } = require('../schemas/response/general-schemas');
 
 module.exports = (db, server) => {
     server.get(
-        { name: 'domainaliases', path: '/domainaliases' },
+        {
+            name: 'domainaliases',
+            path: '/domainaliases',
+            tags: ['DomainAliases'],
+            summary: 'List registered Domain Aliases',
+            validationObjs: {
+                requestBody: {},
+                pathParams: {},
+                queryParams: {
+                    query: Joi.string().trim().empty('').max(255).description('Partial match of a Domain Alias or Domain name'),
+                    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
+                },
+                response: {
+                    200: {
+                        descrition: '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('ID of the Domain Alias'),
+                                        alias: Joi.string().required().description('Domain Alias'),
+                                        domain: Joi.string().required().description('The domain this alias applies to')
+                                    }).$_setFlag('objectName', 'GetDomainAliasesResult')
+                                )
+                                .required()
+                                .description('Aliases listing')
+                        })
+                    }
+                }
+            }
+        },
         tools.responseWrapper(async (req, res) => {
             res.charSet('utf-8');
 
-            const schema = Joi.object().keys({
-                query: Joi.string().trim().empty('').max(255),
-                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,
+                ...queryParams,
+                ...requestBody
             });
 
             const result = schema.validate(req.params, {
@@ -127,21 +166,45 @@ module.exports = (db, server) => {
     );
 
     server.post(
-        '/domainaliases',
+        {
+            path: '/domainaliases',
+            tags: ['DomainAliases'],
+            summary: 'Create new Domain Alias',
+            description: 'Add a new Alias for a Domain. This allows to accept mail on username@domain and username@alias',
+            validationObjs: {
+                requestBody: {
+                    alias: Joi.string()
+                        .max(255)
+                        //.hostname()
+                        .required()
+                        .description('Domain Alias'),
+                    domain: Joi.string()
+                        .max(255)
+                        //.hostname()
+                        .required()
+                        .description('Domain name this Alias applies to'),
+                    sess: sessSchema,
+                    ip: sessIPSchema
+                },
+                queryParams: {},
+                pathParams: {},
+                response: {
+                    200: {
+                        description: 'Success',
+                        model: Joi.object({ success: successRes, id: Joi.string().required().description('ID of the Domain Alias') })
+                    }
+                }
+            }
+        },
         tools.responseWrapper(async (req, res) => {
             res.charSet('utf-8');
 
-            const schema = Joi.object().keys({
-                alias: Joi.string()
-                    .max(255)
-                    //.hostname()
-                    .required(),
-                domain: Joi.string()
-                    .max(255)
-                    //.hostname()
-                    .required(),
-                sess: sessSchema,
-                ip: sessIPSchema
+            const { pathParams, requestBody, queryParams } = req.route.spec.validationObjs;
+
+            const schema = Joi.object({
+                ...pathParams,
+                ...queryParams,
+                ...requestBody
             });
 
             const result = schema.validate(req.params, {
@@ -225,17 +288,40 @@ module.exports = (db, server) => {
     );
 
     server.get(
-        '/domainaliases/resolve/:alias',
+        {
+            path: '/domainaliases/resolve/:alias',
+            tags: ['DomainAliases'],
+            summary: 'Resolve ID for a domain alias',
+            validationObjs: {
+                requestBody: {},
+                pathParams: {
+                    alias: Joi.string()
+                        .max(255)
+                        //.hostname()
+                        .required()
+                        .description('Alias domain')
+                },
+                queryParams: {
+                    sess: sessSchema,
+                    ip: sessIPSchema
+                },
+                response: {
+                    200: {
+                        description: 'Success',
+                        model: Joi.object({ success: successRes, id: Joi.string().required().description('Unique ID (24 byte hex)') })
+                    }
+                }
+            }
+        },
         tools.responseWrapper(async (req, res) => {
             res.charSet('utf-8');
 
-            const schema = Joi.object().keys({
-                alias: Joi.string()
-                    .max(255)
-                    //.hostname()
-                    .required(),
-                sess: sessSchema,
-                ip: sessIPSchema
+            const { pathParams, requestBody, queryParams } = req.route.spec.validationObjs;
+
+            const schema = Joi.object({
+                ...pathParams,
+                ...queryParams,
+                ...requestBody
             });
 
             const result = schema.validate(req.params, {
@@ -291,14 +377,42 @@ module.exports = (db, server) => {
     );
 
     server.get(
-        '/domainaliases/:alias',
+        {
+            path: '/domainaliases/:alias',
+            tags: ['DomainAliases'],
+            summary: 'Request Alias information',
+            validationObjs: {
+                requestBody: {},
+                queryParams: {
+                    sess: sessSchema,
+                    ip: sessIPSchema
+                },
+                pathParams: {
+                    alias: Joi.string().hex().lowercase().length(24).required().description('ID of the Alias')
+                },
+                response: {
+                    200: {
+                        description: 'Success',
+                        model: Joi.object({
+                            success: successRes,
+                            id: Joi.string().required().description('ID of the Alias'),
+                            alias: Joi.string().required().description('Alias domain'),
+                            domain: Joi.string().required().description('Alias target'),
+                            created: Joi.date().required().description('Datestring of the time the alias was created')
+                        })
+                    }
+                }
+            }
+        },
         tools.responseWrapper(async (req, res) => {
             res.charSet('utf-8');
 
-            const schema = Joi.object().keys({
-                alias: Joi.string().hex().lowercase().length(24).required(),
-                sess: sessSchema,
-                ip: sessIPSchema
+            const { pathParams, requestBody, queryParams } = req.route.spec.validationObjs;
+
+            const schema = Joi.object({
+                ...pathParams,
+                ...queryParams,
+                ...requestBody
             });
 
             const result = schema.validate(req.params, {
@@ -352,7 +466,20 @@ module.exports = (db, server) => {
     );
 
     server.del(
-        '/domainaliases/:alias',
+        {
+            path: '/domainaliases/:alias',
+            tags: ['DomainAliases'],
+            summary: 'Delete an Alias',
+            validationObjs: {
+                requestBody: {},
+                pathParams: { alias: Joi.string().hex().lowercase().length(24).required().description('ID of the Alias') },
+                queryParams: {
+                    sess: sessSchema,
+                    ip: sessIPSchema
+                },
+                response: { 200: { description: 'Success', model: Joi.object({ success: successRes }) } }
+            }
+        },
         tools.responseWrapper(async (req, res) => {
             res.charSet('utf-8');