Fix _sanityChecks() method (@apiParam (Group) warning) (#1206)

apidoc · Apr 15, 2022 · 9a2d9d0 · 9a2d9d0
1 parent c9dc48e
commit 9a2d9d0
Show file tree

Hide file tree

Showing 2 changed files with 39 additions and 20 deletions.
diff --git a/lib/core/parser.js b/lib/core/parser.js
@@ -509,10 +509,15 @@ Parser.prototype.findElements = function (block, filename) {
  */
 function _sanityChecks (parsedBlocks, log, filename) {
   for (const block of parsedBlocks) {
-    let paramFields = block.local.parameter && block.local.parameter.fields && block.local.parameter.fields.Parameter;
-    if (!paramFields) {
-      paramFields = [];
+    let paramFields = [];
+
+    if (block.local.parameter && block.local.parameter.fields) {
+      // Loop all fields regardless of the field group. The default field group is `Parameter` but it could be provided by the developer.
+      for (const key in block.local.parameter.fields) {
+        paramFields = paramFields.concat(block.local.parameter.fields[key]);
+      }
     }
+
     const urlParams = [];
     if (block.local.url) {
       // The dummy URL base is only used for parses of relative URLs.
@@ -531,7 +536,8 @@ function _sanityChecks (parsedBlocks, log, filename) {
       }
     }
     for (const paramField of paramFields) {
-      if (!urlParams.some(up => up === paramField.field)) {
+      // Emit the warning only if the field is mandatory.
+      if (!paramField.optional && !urlParams.some(up => up === paramField.field)) {
         log.warn(`@apiParam '${paramField.field}' was defined but does not appear in URL of @api '${block.local.title}' in file: '${filename}'`);
       }
     }

diff --git a/test/core/parse_source_test.js b/test/core/parse_source_test.js
@@ -35,23 +35,24 @@ describe('parseSource', function () {
   const testCases = [
     {
       source:
-        '/**' +
-        '\n            * @api     {post}   /api/school/students/:studentId/cloth  getStudentCloth  ' +
-        '\n            * @apiName         createCloth  ' +
-        '\n            * @apiGroup        cloth  ' +
-        '\n            * @apiParam        id' +
-        '\n            * @apiParam (body) {String}          [name]  ' +
-        '\n            * @apiSuccess      {Number}    code  200  ' +
-        '\n            * @apiSuccessExample {json} Success-Response:  ' +
-        '\n            * {  ' +
-        '\n            *      status: 200  ' +
-        '\n            * }  ' +
-        '\n*/  ',
+        `/**
+          * @api                   {post}   /api/school/students/:studentId/:name/cloth  getStudentCloth
+          * @apiName                        createCloth
+          * @apiGroup                       cloth
+          * @apiParam                       id
+          * @apiParam (body)       {String} name
+          * @apiParam (pagination) {Number} [offset]
+          * @apiSuccess            {Number} code  200
+          * @apiSuccessExample     {json} Success-Response:
+          * {
+          *     status: 200
+          * }
+          */`,
       expected: {
         global: {},
         local: {
           type: 'post',
-          url: '/api/school/students/:studentId/cloth',
+          url: '/api/school/students/:studentId/:name/cloth',
           title: 'getStudentCloth',
           name: 'createCloth',
           group: 'cloth',
@@ -76,11 +77,23 @@ describe('parseSource', function () {
                   description: '',
                   field: 'name',
                   group: 'body',
-                  optional: true,
+                  optional: false,
                   size: undefined,
                   type: 'String',
                 },
               ],
+              pagination: [
+                {
+                  allowedValues: undefined,
+                  defaultValue: undefined,
+                  description: '',
+                  field: 'offset',
+                  group: 'pagination',
+                  optional: true,
+                  size: undefined,
+                  type: 'Number',
+                },
+              ],
             },
           },
           success: {
@@ -100,8 +113,8 @@ describe('parseSource', function () {
             },
             examples: [
               {
-                title: 'Success-Response:  ',
-                content: '{  \n     status: 200  \n}',
+                title: 'Success-Response:',
+                content: '{\n    status: 200\n}',
                 type: 'json',
               },
             ],