fix: Skip case_convention checks on deprecated parameters and properties (#88)

Author: Mike Kistler

README.md

@@ -7,7 +7,8 @@
 
 
 # OpenAPI Validator
-This command line tool lets you validate OpenAPI documents according to their specification, either [2.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md) or [3.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md), as well as [custom IBM-defined best practices](http://watson-developer-cloud.github.io/api-guidelines/swagger-coding-style).
+This command line tool lets you validate OpenAPI documents according to their specification, either [2.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md) or [3.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md),
+as well as IBM-defined best practices.
 
 #### Notice
 Support for Node v8 is deprecated. Support will be officially dropped when it reaches end of life (31 December 2019) or when v1.0 of this package is released, whichever happens first.
@@ -156,12 +157,12 @@ It is recommended to place these files in the root directory of your project. Th
 
 #### Specs
 
-The validator supports two API definition specifications - Swagger 2.0 and OpenAPI 3.0. The validator will automatically determine which spec a document is written in. There are some rules in the validator that only apply to one of the specs and some rules that apply to both. The configuration structure is organized by these "specs".
+The validator supports two API definition specifications - OpenAPI 2.0, aka Swagger 2.0, and OpenAPI 3.0. The validator will automatically determine which spec a document is written in. There are some rules in the validator that only apply to one of the specs and some rules that apply to both. The configuration structure is organized by these "specs".
 The supported specs are described below:
 
 | Spec     | Description                                                                                                                          |
 | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| swagger2 | Rules pertaining only to the [Swagger 2.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md) specification.  |
+| swagger2 | Rules pertaining only to the [OpenAPI 2.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md) specification.  |
 | oas3     | Rules pertaining only to the [OpenAPI 3.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md) specification |
 | shared   | Rules pertaining to both of the above specifications.                                                                                |
 
@@ -256,7 +257,7 @@ The supported rules are described below:
 | Rule                          | Description                                                                  | Spec   |
 | ----------------------------- | ---------------------------------------------------------------------------- | ------ |
 | no_empty_descriptions         | Flag any `description` field in the spec with an empty or whitespace string. | shared |
-| has_circular_references       | Flag any circular references found in the Swagger spec.                      | shared |
+| has_circular_references       | Flag any circular references found in the API document.                      | shared |
 | $ref_siblings                 | Flag any properties that are siblings of a `$ref` property.                  | shared |
 | duplicate_sibling_description | Flag descriptions sibling to `$ref` if identical to referenced description.  | shared |
 | incorrect_ref_pattern        | Flag internal `$ref` values that do not point to the section they should (e.g. referencing `parameters` from a `schema` field). | shared |

src/plugins/validation/2and3/semantic-validators/parameters-ibm.js

@@ -46,8 +46,9 @@ module.exports.validate = function({ jsSpec, isOAS3 }, config) {
 
       const isParameter = obj.in; // the `in` property is required by OpenAPI for parameters - this should be true (unless obj is a ref)
       const isHeaderParameter = obj.in && obj.in.toLowerCase() === 'header'; // header params need not be checked for case
+      const isDeprecated = obj.deprecated === true;
 
-      if (isParameter && !isHeaderParameter && !isRef) {
+      if (isParameter && !isHeaderParameter && !isRef && !isDeprecated) {
         const checkStatus = config.param_name_case_convention[0];
         if (checkStatus !== 'off') {
           const caseConvention = config.param_name_case_convention[1];

src/plugins/validation/2and3/semantic-validators/schema-ibm.js

@@ -299,6 +299,9 @@ function checkPropNames(schema, contextPath, config) {
   forIn(schema.properties, (property, propName) => {
     if (propName.slice(0, 2) === 'x-') return;
 
+    // Skip snake_case_only checks for deprecated properties
+    if (property.deprecated === true) return;
+
     const checkStatus = config.snake_case_only || 'off';
     if (checkStatus.match('error|warning')) {
       if (!isSnakecase(propName)) {
@@ -335,6 +338,9 @@ function checkPropNamesCaseConvention(schema, contextPath, caseConvention) {
   forIn(schema.properties, (property, propName) => {
     if (propName.slice(0, 2) === 'x-') return;
 
+    // Skip case_convention checks for deprecated properties
+    if (property.deprecated === true) return;
+
     const checkStatus = caseConvention[0] || 'off';
     if (checkStatus.match('error|warning')) {
       const caseConventionValue = caseConvention[1];

test/plugins/validation/2and3/parameters-ibm.js

@@ -95,6 +95,30 @@ describe('validation plugin - semantic - parameters-ibm', () => {
       expect(res.warnings.length).toEqual(0);
     });
 
+    it('should not return a case_convention error when parameter is deprecated', () => {
+      const spec = {
+        paths: {
+          '/pets': {
+            get: {
+              parameters: [
+                {
+                  name: 'camelCase',
+                  in: 'query',
+                  description: 'description',
+                  type: 'string',
+                  deprecated: true
+                }
+              ]
+            }
+          }
+        }
+      };
+
+      const res = validate({ jsSpec: spec }, config);
+      expect(res.errors.length).toEqual(0);
+      expect(res.warnings.length).toEqual(0);
+    });
+
     it('should return an error when type does not match format', () => {
       const spec = {
         paths: {

test/plugins/validation/2and3/schema-ibm.js

@@ -492,6 +492,35 @@ describe('validation plugin - semantic - schema-ibm - Swagger 2', () => {
     expect(res.warnings.length).toEqual(0);
   });
 
+  it('should not return a case_convention error when property is deprecated', () => {
+    const config = {
+      schemas: {
+        snake_case_only: 'off',
+        property_case_convention: ['error', 'lower_snake_case']
+      }
+    };
+
+    const spec = {
+      definitions: {
+        Thing: {
+          type: 'object',
+          description: 'thing',
+          properties: {
+            thingName: {
+              type: 'string',
+              description: 'thing name',
+              deprecated: true
+            }
+          }
+        }
+      }
+    };
+
+    const res = validate({ jsSpec: spec }, config);
+    expect(res.errors.length).toEqual(0);
+    expect(res.warnings.length).toEqual(0);
+  });
+
   it('should return an error when a schema has no description', () => {
     const config = {
       schemas: {