fix: raises warning for tag that hasnt been defined in global tags list

Author: SamerJaser96

README.md

@@ -182,6 +182,7 @@ The supported rules are described below:
 ##### operations
 | Rule                         | Description                                                                         | Spec     |
 | ---------------------------- | ----------------------------------------------------------------------------------- | -------- |
+| unused_tag                   | Flag a tag that is in operations and not listed in `tags` on the top level.         | shared   |
 | no_consumes_for_put_or_post  | Flag `put` or `post` operations that do not have a `consumes` field.                | swagger2 |
 | get_op_has_consumes          | Flag `get` operations that contain a `consumes` field.                              | swagger2 |
 | no_produces                  | Flag operations that do not have a `produces` field (except for `head` and operations that return a 204). | swagger2 |
@@ -344,6 +345,7 @@ The default values for each rule are described below.
 ###### operations
 | Rule                         | Default |
 | ---------------------------- | ------- |
+| unused_tag                   | warning |
 | no_operation_id              | warning |
 | operation_id_case_convention | warning, lower_snake_case |
 | no_summary                   | warning |

src/.defaultsForValidator.js

@@ -25,7 +25,8 @@ const defaults = {
       'operation_id_case_convention': ['warning', 'lower_snake_case'],
       'no_summary': 'warning',
       'no_array_responses': 'error',
-      'parameter_order': 'warning'
+      'parameter_order': 'warning',
+      'unused_tag': 'warning'
     },
     'parameters': {
       'no_parameter_description': 'error',

src/plugins/validation/2and3/semantic-validators/operations-shared.js

@@ -119,6 +119,25 @@ module.exports.validate = function({ resolvedSpec, isOAS3 }, config) {
           });
         }
       }
+      const hasOperationTags = op.tags && op.tags.length > 0;
+      const hasGlobalTags = resolvedSpec.tags && resolvedSpec.tags.length > 0;
+      const resolvedTags = [];
+      if (hasOperationTags && hasGlobalTags) {
+        for (let i = 0; i < resolvedSpec.tags.length; i++) {
+          resolvedTags.push(resolvedSpec.tags[i].name);
+        }
+        for (let i = 0, len = op.tags.length; i < len; i++) {
+          if (!resolvedTags.includes(op.tags[i])) {
+            const checkStatus = config.unused_tag;
+            if (checkStatus !== 'off') {
+              result[checkStatus].push({
+                path: `paths.${pathKey}.${opKey}.tags`,
+                message: 'tag is not defined at the global level: ' + op.tags[i]
+              });
+            }
+          }
+        }
+      }
 
       const hasSummary =
         op.summary && op.summary.length > 0 && !!op.summary.toString().trim();

test/plugins/validation/2and3/operations-shared.js

@@ -715,5 +715,48 @@ describe('validation plugin - semantic - operations-shared', function() {
       );
       expect(res.warnings.length).toEqual(0);
     });
+
+    it('should complain about an unused tag', function() {
+      const spec = {
+        tags: [
+          {
+            name: 'some tag'
+          },
+          {
+            name: 'some other tag'
+          }
+        ],
+        paths: {
+          '/': {
+            get: {
+              operationId: 'get_everything',
+              tags: ['not a tag'],
+              summary: 'get everything as a string',
+              responses: {
+                '200': {
+                  content: {
+                    'text/plain': {
+                      schema: {
+                        type: 'string'
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      };
+
+      const res = validate({ resolvedSpec: spec, isOAS3: true }, config);
+      console.log(res);
+      expect(res.errors.length).toEqual(0);
+      expect(res.warnings.length).toEqual(1);
+
+      expect(res.warnings[0].path).toEqual('paths./.get.tags');
+      expect(res.warnings[0].message).toEqual(
+        'tag is not defined at the global level: not a tag'
+      );
+    });
   });
 });