fix(docs): Fixed descriptions ZMS-101 (#553)

* api.js added endpoint for generating openapi docs. added new info to one route in mailboxes.js and messages.js files so that the api docs generation can be done at all

* try to first generate json representation of the api docs

* add initial Joi Object parsing

* api.js make generation dynamic. messages.js add schemas from separate file. messages-schemas.js used for messages endpoint schemas

* add additions to schemas. Add new schemas to messages.js and also add response object there. Add response object parsing functionality to api.js

* add initial openapi doc yml file generation

* remove manual yaml parsing with js-yaml JSON -> YAML parsing

* fix replaceWithRefs and parseComponentsDecoupled functions, refactor, remove unnecessary comments and logs

* add support for another endpoint

* move big code from api.js to tools

* fix array type representation, fix response objects, add necessary data and changes to endpoints

* redo include logic into exclude login

* fix api generation in tools.js to accomodate new naming of objects

* fix messages.js, add structuredClone check in tools.js

* fix structured clone definition

* add one endpoint in messages.js to the api generation

* messages.js add one more endpoint to API generation

* add response to prev commit. Add new endpoint to API generation. Archive message and archive messages

* finish with post endpoints in messages.js

* added general request and response schemas. Also added req and res schemas for messages

* add multiple GET endpoints to API generation and changed them to new design. Use general schemas made earlier

* fix incorrect import of successRes

* fix mailboxes.js

* refactor general-schemas.js. Fix searchSchema in messages.js. Mailboxes.js fix response

* tools.js rename methodObj in API generation to operationObj

* tools.js api generation remove string fallbacks

* messages.js finish with GET endpoints, addition to API doc generation

* fix description on the object issue

* add descriptions to fields for the schemas in the messages-schemas.js file

* remove yarml import in tools.js

lib/schemas/request/messages-schemas.js

@@ -2,52 +2,60 @@
 
 const Joi = require('joi');
 const { booleanSchema } = require('../../schemas');
+const { mailboxId, messageId } = require('./general-schemas');
 
 const Address = Joi.object({
-    name: Joi.string().empty('').max(255),
-    address: Joi.string().email({ tlds: false }).required()
+    name: Joi.string().empty('').max(255).required().description('Name of the sender/recipient'),
+    address: Joi.string().email({ tlds: false }).required().description('Address of the sender/recipient')
 }).$_setFlag('objectName', 'Address');
 
 const AddressOptionalName = Joi.object({
-    name: Joi.string().empty('').max(255),
-    address: Joi.string().email({ tlds: false }).required()
+    name: Joi.string().empty('').max(255).description('Name of the sender'),
+    address: Joi.string().email({ tlds: false }).required().description('Address of the sender')
 }).$_setFlag('objectName', 'AddressOptionalName');
 
 const AddressOptionalNameArray = Joi.array().items(AddressOptionalName);
 
 const Header = Joi.object({
-    key: Joi.string().empty('').max(255),
+    key: Joi.string().empty('').max(255).required().description("Header key ('X-Mailer')"),
     value: Joi.string()
         .empty('')
         .max(100 * 1024)
+        .required()
+        .description("Header value ('My Awesome Mailing Service')")
 }).$_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)
+    filename: Joi.string().empty('').max(255).description('Attachment filename'),
+    contentType: Joi.string().empty('').max(255).description('MIME type for the attachment file'),
+    encoding: Joi.string().empty('').default('base64').description('Encoding to use to store the attachments'),
+    contentTransferEncoding: Joi.string().empty('').description('Transfer encoding'),
+    content: Joi.string().required().description('Base64 encoded attachment content'),
+    cid: Joi.string().empty('').max(255).description('Content-ID value if you want to reference to this attachment from HTML formatted message')
 }).$_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()
+    mailbox: mailboxId,
+    id: messageId,
+    action: Joi.string().valid('reply', 'replyAll', 'forward').required().description('Either reply, replyAll or forward'),
+    attachments: Joi.alternatives()
+        .try(
+            booleanSchema,
+            Joi.array().items(
+                Joi.string()
+                    .regex(/^ATT\d+$/i)
+                    .uppercase()
+            )
+        )
+        .required()
+        .description(
+            "If true, then includes all attachments from the original message. If it is an array of attachment ID's includes attachments from the list"
         )
-    )
 }).$_setFlag('objectName', 'ReferenceWithAttachments');
 
 const Bimi = Joi.object({
-    domain: Joi.string().domain().required(),
-    selector: Joi.string().empty('').max(255)
+    domain: Joi.string().domain().required().description('Domain name for the BIMI record. It does not have to be the same as the From address.'),
+    selector: Joi.string().empty('').max(255).description('Optional BIMI selector')
 }).$_setFlag('objectName', 'Bimi');
 
 module.exports = {

lib/tools.js

@@ -627,7 +627,7 @@ function replaceWithRefs(reqBodyData) {
         if (reqBodyData.objectName) {
             const objectName = reqBodyData.objectName;
             Object.keys(reqBodyData).forEach(key => {
-                if (key !== '$ref') {
+                if (key !== '$ref' || key !== 'description') {
                     delete reqBodyData[key];
                 }
             });