From 3c9e17595cffd32475f51aa104ab09d721989e6f Mon Sep 17 00:00:00 2001 From: NickOvt <nikolai@zone.ee> Date: Thu, 30 Nov 2023 14:27:00 +0200 Subject: [PATCH] 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 | 54 ++++++++++++++----------- lib/tools.js | 2 +- 2 files changed, 32 insertions(+), 24 deletions(-) diff --git a/lib/schemas/request/messages-schemas.js b/lib/schemas/request/messages-schemas.js index d4226e60..f0844283 100644 --- a/lib/schemas/request/messages-schemas.js +++ b/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 = { diff --git a/lib/tools.js b/lib/tools.js index 85f59d3c..fb96ce57 100644 --- a/lib/tools.js +++ b/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]; } });