Tags property parsing refactoring (#36)

Author: kalinchernev

.gitignore

@@ -29,5 +29,6 @@ node_modules
 # JSDoc
 jsdoc
 
-# Cloud9 editor
+# Editors
 .c9
+.idea

example/routes.js

@@ -33,14 +33,14 @@ module.exports.setup = function(app) {
 
   /**
    * @swagger
-   * tag:
+   * tags:
    *   name: Users
    *   description: User management and login
    */
 
   /**
    * @swagger
-   * tag:
+   * tags:
    *   - name: Login
    *     description: Login
    *   - name: Accounts
@@ -52,7 +52,7 @@ module.exports.setup = function(app) {
    * /login:
    *   post:
    *     description: Login to the application
-   *     tag: [Users, Login]
+   *     tags: [Users, Login]
    *     produces:
    *       - application/json
    *     parameters:
@@ -78,7 +78,7 @@ module.exports.setup = function(app) {
    * /users:
    *   get:
    *     description: Returns users
-   *     tag:
+   *     tags:
    *      - Users
    *     produces:
    *      - application/json
@@ -97,7 +97,7 @@ module.exports.setup = function(app) {
    * /users:
    *   post:
    *     description: Returns users
-   *     tag: [Users]
+   *     tags: [Users]
    *     produces:
    *       - application/json
    *     parameters:

lib/index.js

@@ -88,6 +88,42 @@ function objectMerge(obj1, obj2) {
   return obj3;
 }
 
+/**
+ * Yields a warning for a given deprecated property.
+ * @function
+ * @param {string} propertyName - The property to warn about.
+ */
+function deprecatedPropertyWarning(propertyName) {
+  if (propertyName === 'tag') {
+    console.warn('tag will be deprecated in v2.0.0');
+    console.warn('Please use tags as it aligns with the swagger v2.0 spec.');
+  }
+}
+
+/**
+ * Adds the tags property to a swagger object.
+ * @function
+ * @param {object} conf - Flexible configuration.
+ */
+function attachTags(conf) {
+  var tag = conf.tag;
+  var swaggerObject = conf.swaggerObject;
+  var propertyName = conf.propertyName;
+
+  // Correct deprecated property.
+  if (propertyName === 'tag') {
+    propertyName = 'tags';
+  }
+
+  if (Array.isArray(tag)) {
+    for (var i = 0; i < tag.length; i = i + 1) {
+      swaggerObject[propertyName].push(tag[i]);
+    }
+  } else {
+    swaggerObject[propertyName].push(tag);
+  }
+}
+
 /**
  * Adds the data in to the swagger object.
  * @function
@@ -99,14 +135,15 @@ function addDataToSwaggerObject(swaggerObject, data) {
   for (var i = 0; i < data.length; i = i + 1) {
     var pathObject = data[i];
     var propertyNames = Object.getOwnPropertyNames(pathObject);
+    // Iterating the properties of the a given pathObject.
     for (var j = 0; j < propertyNames.length; j = j + 1) {
       var propertyName = propertyNames[j];
-      var keyName = propertyName + 's';
       switch (propertyName) {
         case 'securityDefinition':
         case 'response':
         case 'parameter':
         case 'definition': {
+          var keyName = propertyName + 's';
           var definitionNames = Object
             .getOwnPropertyNames(pathObject[propertyName]);
           for (var k = 0; k < definitionNames.length; k = k + 1) {
@@ -116,17 +153,18 @@ function addDataToSwaggerObject(swaggerObject, data) {
           }
           break;
         }
-        case 'tag': {
+        case 'tag':
+        case 'tags': {
+          deprecatedPropertyWarning(propertyName);
           var tag = pathObject[propertyName];
-          if (Array.isArray(tag)) {
-            for (var t = 0; t < tag.length; t = t + 1) {
-              swaggerObject[keyName].push(tag[t]);
-            }
-          } else {
-            swaggerObject[keyName].push(tag);
-          }
+          attachTags({
+            tag: tag,
+            swaggerObject: swaggerObject,
+            propertyName: propertyName,
+          });
           break;
         }
+        // Assumes a path property if nothing else matches.
         default: {
           swaggerObject.paths[propertyName] = objectMerge(
             swaggerObject.paths[propertyName], pathObject[propertyName]

test/swagger-spec.json

@@ -21,25 +21,22 @@
     "/login": {
       "post": {
         "description": "Login to the application",
-        "tag": [
+        "tags": [
           "Users",
           "Login"
         ],
         "produces": [
           "application/json"
         ],
-        "parameters": [
-          {
-            "$ref": "#/parameters/username"
-          },
-          {
-            "name": "password",
-            "description": "User's password.",
-            "in": "formData",
-            "required": true,
-            "type": "string"
-          }
-        ],
+        "parameters": [{
+          "$ref": "#/parameters/username"
+        }, {
+          "name": "password",
+          "description": "User's password.",
+          "in": "formData",
+          "required": true,
+          "type": "string"
+        }],
         "responses": {
           "200": {
             "description": "login",
@@ -54,7 +51,7 @@
     "/users": {
       "get": {
         "description": "Returns users",
-        "tag": [
+        "tags": [
           "Users"
         ],
         "produces": [
@@ -68,17 +65,15 @@
       },
       "post": {
         "description": "Returns users",
-        "tag": [
+        "tags": [
           "Users"
         ],
         "produces": [
           "application/json"
         ],
-        "parameters": [
-          {
-            "$ref": "#/parameters/username"
-          }
-        ],
+        "parameters": [{
+          "$ref": "#/parameters/username"
+        }],
         "responses": {
           "200": {
             "description": "users"
@@ -124,18 +119,14 @@
     }
   },
   "securityDefinitions": {},
-  "tags": [
-    {
-      "name": "Users",
-      "description": "User management and login"
-    },
-    {
-      "name": "Login",
-      "description": "Login"
-    },
-    {
-      "name": "Accounts",
-      "description": "Accounts"
-    }
-  ]
-}
+  "tags": [{
+    "name": "Users",
+    "description": "User management and login"
+  }, {
+    "name": "Login",
+    "description": "Login"
+  }, {
+    "name": "Accounts",
+    "description": "Accounts"
+  }]
+}

test/test.js

@@ -8,62 +8,53 @@ var swaggerSpec = require('./swagger-spec.json');
 
 
 // Check against saved swagger spec
-function equalsToBeSwaggerSpec(res) {
-
+function swaggerSpecIsCompliant(res) {
   // Check if result equals expected spec
   if (JSON.stringify(res.body) !== JSON.stringify(swaggerSpec)) {
     throw new Error('Returned spec does not equal the expected result');
   }
-
 }
 
-
-describe('example app', function() {
-
-  it('homepage', function(done) {
+// Testing an example app parsing documentation with swagger-jsdoc.
+describe('example app', function () {
+  it('homepage returns a success code', function (done) {
     request(app)
       .get('/')
       .expect(200)
-      .end(function(err) {
+      .end(function (err) {
         if (err) {
           return done(err);
         }
         done();
       });
   });
 
-  it('login', function(done) {
+  it('login authentication returns a success code', function (done) {
     request(app)
       .post('/login')
       .send({
         username: 'user@domain.com',
         password: 'Password',
       })
       .expect(200)
-      .end(function(err) {
+      .end(function (err) {
         if (err) {
           return done(err);
         }
         done();
       });
   });
 
-});
-
-
-describe('swagger spec', function() {
-
-  it('equals expected result', function(done) {
+  it('produced swagger spec is as expected', function (done) {
     request(app)
       .get('/api-docs.json')
       .expect(200)
-      .expect(equalsToBeSwaggerSpec)
-      .end(function(err) {
+      .expect(swaggerSpecIsCompliant)
+      .end(function (err) {
         if (err) {
           return done(err);
         }
         done();
       });
   });
-
 });