Preparing for general reporting of deprecated properties.

Author: kalinchernev

lib/index.js

@@ -104,6 +104,15 @@ module.exports = function(options) {
   for (var i = 0; i < apiPaths.length; i = i + 1) {
     var files = parseApiFile(apiPaths[i]);
     var swaggerJsDocComments = filterJsDocComments(files.jsdoc);
+
+    var problems = swaggerHelpers.findDeprecated([files, swaggerJsDocComments]);
+    // Report a warning in case potential problems encountered.
+    if (problems.length > 0) {
+      console.warn('You are using properties to be deprecated in v2.0.0');
+      console.warn('Please update to align with the swagger v2.0 spec.');
+      console.warn(problems);
+    }
+
     swaggerHelpers.addDataToSwaggerObject(swaggerObject, files.yaml);
     swaggerHelpers.addDataToSwaggerObject(swaggerObject, swaggerJsDocComments);
   }

lib/swagger-helpers.js

@@ -1,17 +1,5 @@
 'use strict';
 
-/**
- * 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
@@ -77,15 +65,19 @@ function swaggerizeObj(swaggerObject) {
 }
 
 /**
- * List of deprecated property names.
+ * List of deprecated or wrong swagger schema properties in singular.
  * @function
  * @returns {array} The list of deprecated property names.
  */
-function _getDeprecatePropertyNames() {
+function _getSwaggerSchemaWrongProperties() {
   return [
+    'consume',
+    'produce',
+    'path',
     'tag',
     'definition',
     'securityDefinition',
+    'scheme',
     'response',
     'parameter',
   ];
@@ -97,9 +89,9 @@ function _getDeprecatePropertyNames() {
  * @param {string} propertyName - The swagger property name to check.
  * @returns {string} The updated propertyName if neccessary.
  */
-function _getSwaggerKey(propertyName) {
-  var deprecated = _getDeprecatePropertyNames();
-  if (deprecated.indexOf(propertyName) > 0) {
+function _correctSwaggerKey(propertyName) {
+  var wrong = _getSwaggerSchemaWrongProperties();
+  if (wrong.indexOf(propertyName) > 0) {
     // Returns the corrected property name.
     return propertyName + 's';
   }
@@ -115,6 +107,14 @@ function _getSwaggerKey(propertyName) {
  */
 function _organizeSwaggerProperties(swaggerObject, pathObject, propertyName) {
   var simpleProperties = [
+    'consume',
+    'consumes',
+    'produce',
+    'produces',
+    'path',
+    'paths',
+    'schema',
+    'schemas',
     'securityDefinition',
     'securityDefinitions',
     'response',
@@ -127,7 +127,7 @@ function _organizeSwaggerProperties(swaggerObject, pathObject, propertyName) {
 
   // Common properties.
   if (simpleProperties.indexOf(propertyName) !== -1) {
-    var keyName = _getSwaggerKey(propertyName);
+    var keyName = _correctSwaggerKey(propertyName);
     var definitionNames = Object
       .getOwnPropertyNames(pathObject[propertyName]);
     for (var k = 0; k < definitionNames.length; k = k + 1) {
@@ -137,7 +137,6 @@ function _organizeSwaggerProperties(swaggerObject, pathObject, propertyName) {
     }
   // Tags.
   } else if (propertyName === 'tag' || propertyName === 'tags') {
-    _deprecatedPropertyWarning(propertyName);
     var tag = pathObject[propertyName];
     _attachTags({
       tag: tag,
@@ -156,7 +155,7 @@ function _organizeSwaggerProperties(swaggerObject, pathObject, propertyName) {
  * Adds the data in to the swagger object.
  * @function
  * @param {object} swaggerObject - Swagger object which will be written to
- * @param {object[]} data - objects of parsed swagger data from yaml or jsDoc
+ * @param {object[]} data - objects of parsed swagger data from yml or jsDoc
  *                          comments
  */
 function addDataToSwaggerObject(swaggerObject, data) {
@@ -176,7 +175,25 @@ function addDataToSwaggerObject(swaggerObject, data) {
   }
 }
 
+/**
+ * Returns a list of problematic tags if any.
+ * @param sources
+ * @returns {Array}
+ */
+function findDeprecated(sources) {
+  var wrong = _getSwaggerSchemaWrongProperties();
+
+  var problems = [];
+  sources.forEach(function(source) {
+    // Transverse the source for wrong usages.
+    console.log(source);
+  });
+
+  return problems;
+}
+
 module.exports = {
   addDataToSwaggerObject: addDataToSwaggerObject,
   swaggerizeObj: swaggerizeObj,
+  findDeprecated: findDeprecated,
 };