ZMS-[9x] Automatic API generation

api.js

@@ -573,6 +573,17 @@ module.exports = done => {
         );
     }
 
+    server.get(
+        { path: '/openapi', name: 'openapi-docs-generation' },
+        tools.responseWrapper(async (req, res) => {
+            res.charSet('utf-8');
+
+            const routes = server.router.getRoutes();
+
+            tools.generateAPiDocs(routes);
+        })
+    );
+
     server.on('error', err => {
         if (!started) {
             started = true;

lib/api/mailboxes.js

@@ -246,19 +246,29 @@ module.exports = (db, server, mailboxHandler) => {
     );
 
     server.post(
-        '/users/:user/mailboxes',
-        tools.responseWrapper(async (req, res) => {
-            res.charSet('utf-8');
-
-            const schema = Joi.object().keys({
-                user: Joi.string().hex().lowercase().length(24).required(),
+        {
+            path: '/users/:user/mailboxes',
+            pathParams: { user: Joi.string().hex().lowercase().length(24).required().description('This is the user path param') },
+            description: 'Some description for the API path',
+            requestBody: {
                 path: Joi.string()
                     .regex(/\/{2,}|\/$/, { invert: true })
                     .required(),
                 hidden: booleanSchema.default(false),
-                retention: Joi.number().min(0),
-                sess: sessSchema,
-                ip: sessIPSchema
+                retention: Joi.number().min(0)
+            },
+            queryParams: { sess: sessSchema, ip: sessIPSchema },
+            tags: ['Mailboxes']
+        },
+        tools.responseWrapper(async (req, res) => {
+            res.charSet('utf-8');
+
+            const { pathParams, requestBody, queryParams } = req.route.spec;
+
+            const schema = Joi.object({
+                ...pathParams,
+                ...requestBody,
+                ...queryParams
             });
 
             const result = schema.validate(req.params, {

lib/api/messages.js

@@ -25,6 +25,7 @@ const { getMongoDBQuery /*, getElasticSearchQuery*/ } = require('../search-query
 //const { getClient } = require('../elasticsearch');
 
 const BimiHandler = require('../bimi-handler');
+const { Address, AddressOptionalNameArray, Header, Attachment, ReferenceWithAttachments, Bimi } = require('../schemas/request/messages-schemas');
 
 module.exports = (db, server, messageHandler, userHandler, storageHandler, settingsHandler) => {
     let maildrop = new Maildropper({
@@ -1529,114 +1530,91 @@ module.exports = (db, server, messageHandler, userHandler, storageHandler, setti
     );
 
     server.post(
-        '/users/:user/mailboxes/:mailbox/messages',
-        tools.responseWrapper(async (req, res) => {
-            res.charSet('utf-8');
+        {
+            path: '/users/:user/mailboxes/:mailbox/messages',
+            summary: 'Upload Message',
+            description:
+                'This method allows to upload either an RFC822 formatted message or a message structure to a mailbox. Raw message is stored unmodified, no headers are added or removed. If you want to generate the uploaded message from structured data fields, then do not use the raw property.',
+            validationObjs: {
+                pathParams: {
+                    user: Joi.string().hex().lowercase().length(24).required(),
+                    mailbox: Joi.string().hex().lowercase().length(24).required()
+                },
+                requestBody: {
+                    date: Joi.date(),
+                    unseen: booleanSchema.default(false),
+                    flagged: booleanSchema.default(false),
+                    draft: booleanSchema.default(false),
 
-            const schema = Joi.object().keys({
-                user: Joi.string().hex().lowercase().length(24).required(),
-                mailbox: Joi.string().hex().lowercase().length(24).required(),
-                date: Joi.date(),
-                unseen: booleanSchema.default(false),
-                flagged: booleanSchema.default(false),
-                draft: booleanSchema.default(false),
+                    raw: Joi.binary().max(consts.MAX_ALLOWED_MESSAGE_SIZE).empty(''),
 
-                raw: Joi.binary().max(consts.MAX_ALLOWED_MESSAGE_SIZE).empty(''),
+                    from: Address,
 
-                from: Joi.object().keys({
-                    name: Joi.string().empty('').max(255),
-                    address: Joi.string().email({ tlds: false }).required()
-                }),
+                    replyTo: Address,
 
-                replyTo: Joi.object().keys({
-                    name: Joi.string().empty('').max(255),
-                    address: Joi.string().email({ tlds: false }).required()
-                }),
+                    to: AddressOptionalNameArray,
 
-                to: Joi.array().items(
-                    Joi.object().keys({
-                        name: Joi.string().empty('').max(255),
-                        address: Joi.string().email({ tlds: false }).required()
-                    })
-                ),
+                    cc: AddressOptionalNameArray,
 
-                cc: Joi.array().items(
-                    Joi.object().keys({
-                        name: Joi.string().empty('').max(255),
-                        address: Joi.string().email({ tlds: false }).required()
-                    })
-                ),
+                    bcc: AddressOptionalNameArray,
 
-                bcc: Joi.array().items(
-                    Joi.object().keys({
-                        name: Joi.string().empty('').max(255),
-                        address: Joi.string().email({ tlds: false }).required()
-                    })
-                ),
-
-                headers: Joi.array().items(
-                    Joi.object().keys({
-                        key: Joi.string().empty('').max(255),
-                        value: Joi.string()
-                            .empty('')
-                            .max(100 * 1024)
-                    })
-                ),
+                    headers: Joi.array().items(Header),
 
-                subject: Joi.string()
-                    .empty('')
-                    .max(2 * 1024),
-                text: Joi.string()
-                    .empty('')
-                    .max(1024 * 1024),
-                html: Joi.string()
-                    .empty('')
-                    .max(1024 * 1024),
+                    subject: Joi.string()
+                        .empty('')
+                        .max(2 * 1024),
+                    text: Joi.string()
+                        .empty('')
+                        .max(1024 * 1024),
+                    html: Joi.string()
+                        .empty('')
+                        .max(1024 * 1024),
 
-                files: Joi.array().items(Joi.string().hex().lowercase().length(24)),
+                    files: Joi.array().items(Joi.string().hex().lowercase().length(24)),
 
-                attachments: Joi.array().items(
-                    Joi.object().keys({
-                        filename: Joi.string().empty('').max(255),
+                    attachments: Joi.array().items(Attachment),
 
-                        contentType: Joi.string().empty('').max(255),
-                        contentTransferEncoding: Joi.string().empty(''),
-                        contentDisposition: Joi.string().empty('').trim().lowercase().valid('inline', 'attachment'),
-                        cid: Joi.string().empty('').max(255),
+                    metaData: metaDataSchema.label('metaData'),
 
-                        encoding: Joi.string().empty('').default('base64'),
-                        content: Joi.string().required()
-                    })
-                ),
+                    reference: ReferenceWithAttachments,
 
-                metaData: metaDataSchema.label('metaData'),
+                    replacePrevious: Joi.object({
+                        mailbox: Joi.string().hex().lowercase().length(24),
+                        id: Joi.number().required()
+                    }),
 
-                reference: Joi.object().keys({
-                    mailbox: Joi.string().hex().lowercase().length(24).required(),
-                    id: Joi.number().required(),
-                    action: Joi.string().valid('reply', 'replyAll', 'forward').required(),
-                    attachments: Joi.alternatives().try(
-                        booleanSchema,
-                        Joi.array().items(
-                            Joi.string()
-                                .regex(/^ATT\d+$/i)
-                                .uppercase()
-                        )
-                    )
-                }),
+                    bimi: Bimi,
 
-                replacePrevious: Joi.object({
-                    mailbox: Joi.string().hex().lowercase().length(24),
-                    id: Joi.number().required()
-                }),
+                    sess: sessSchema,
+                    ip: sessIPSchema
+                },
+                queryParams: {},
+                response: {
+                    200: {
+                        description: 'Success',
+                        model: Joi.object({
+                            success: Joi.boolean(),
+                            message: Joi.object({
+                                id: Joi.number(),
+                                malbox: Joi.string(),
+                                size: Joi.number()
+                            }),
+                            previousDeleted: Joi.boolean()
+                        })
+                    }
+                }
+            },
+            tags: ['Messages']
+        },
+        tools.responseWrapper(async (req, res) => {
+            res.charSet('utf-8');
 
-                bimi: Joi.object().keys({
-                    domain: Joi.string().domain().required(),
-                    selector: Joi.string().empty('').max(255)
-                }),
+            const { pathParams, requestBody, queryParams } = req.route.spec.validationObjs;
 
-                sess: sessSchema,
-                ip: sessIPSchema
+            const schema = Joi.object({
+                ...pathParams,
+                ...requestBody,
+                ...queryParams
             });
 
             if (!req.params.raw && req.body && (Buffer.isBuffer(req.body) || typeof req.body === 'string')) {
@@ -1983,18 +1961,52 @@ module.exports = (db, server, messageHandler, userHandler, storageHandler, setti
     );
 
     server.post(
-        '/users/:user/mailboxes/:mailbox/messages/:message/forward',
+        {
+            path: '/users/:user/mailboxes/:mailbox/messages/:message/forward',
+            validationObjs: {
+                pathParams: {
+                    user: Joi.string().hex().lowercase().length(24).required(),
+                    mailbox: Joi.string().hex().lowercase().length(24).required(),
+                    message: Joi.number().required()
+                },
+                queryParams: {},
+                requestBody: {
+                    target: Joi.number().min(1).max(1000),
+                    addresses: Joi.array().items(Joi.string().email({ tlds: false })),
+                    sess: sessSchema,
+                    ip: sessIPSchema
+                },
+                response: {
+                    200: {
+                        description: 'Success',
+                        model: Joi.object({
+                            success: Joi.boolean(),
+                            queueId: Joi.string(),
+                            forwarded: Joi.array().items(
+                                Joi.object({
+                                    seq: Joi.string(),
+                                    type: Joi.string(),
+                                    value: Joi.string()
+                                }).$_setFlag('objectName', 'Forwarded')
+                            )
+                        })
+                    }
+                }
+            },
+            summary: 'Forward stored Message',
+            description:
+                'This method allows either to re-forward a message to an original forward target or forward it to some other address. This is useful if a user had forwarding turned on but the message was not delivered so you can try again. Forwarding does not modify the original message.',
+            tags: ['Messages']
+        },
         tools.responseWrapper(async (req, res) => {
             res.charSet('utf-8');
 
-            const schema = Joi.object().keys({
-                user: Joi.string().hex().lowercase().length(24).required(),
-                mailbox: Joi.string().hex().lowercase().length(24).required(),
-                message: Joi.number().required(),
-                target: Joi.number().min(1).max(1000),
-                addresses: Joi.array().items(Joi.string().email({ tlds: false })),
-                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, {

lib/schemas/request/messages-schemas.js

@@ -0,0 +1,60 @@
+'use strict';
+
+const Joi = require('joi');
+const { booleanSchema } = require('../../schemas');
+
+const Address = Joi.object({
+    name: Joi.string().empty('').max(255),
+    address: Joi.string().email({ tlds: false }).required()
+}).$_setFlag('objectName', 'Address');
+
+const AddressOptionalName = Joi.object({
+    name: Joi.string().empty('').max(255),
+    address: Joi.string().email({ tlds: false }).required()
+}).$_setFlag('objectName', 'AddressOptionalName');
+
+const AddressOptionalNameArray = Joi.array().items(AddressOptionalName);
+
+const Header = Joi.object({
+    key: Joi.string().empty('').max(255),
+    value: Joi.string()
+        .empty('')
+        .max(100 * 1024)
+}).$_setFlag('objectName', 'Header');
+
+const Attachment = Joi.object({
+    filename: Joi.string().empty('').max(255),
+    contentType: Joi.string().empty('').max(255),
+    encoding: Joi.string().empty('').default('base64'),
+    contentTransferEncoding: Joi.string().empty(''),
+    content: Joi.string().required(),
+    cid: Joi.string().empty('').max(255)
+}).$_setFlag('objectName', 'Attachment');
+
+const ReferenceWithAttachments = Joi.object({
+    mailbox: Joi.string().hex().lowercase().length(24).required(),
+    id: Joi.number().required(),
+    action: Joi.string().valid('reply', 'replyAll', 'forward').required(),
+    attachments: Joi.alternatives().try(
+        booleanSchema,
+        Joi.array().items(
+            Joi.string()
+                .regex(/^ATT\d+$/i)
+                .uppercase()
+        )
+    )
+}).$_setFlag('objectName', 'ReferenceWithAttachments');
+
+const Bimi = Joi.object({
+    domain: Joi.string().domain().required(),
+    selector: Joi.string().empty('').max(255)
+}).$_setFlag('objectName', 'Bimi');
+
+module.exports = {
+    Address,
+    AddressOptionalNameArray,
+    Header,
+    Attachment,
+    ReferenceWithAttachments,
+    Bimi
+};