added documentation for new rule

docs/source/rules/REQ-E004.rst

@@ -0,0 +1,40 @@
+[REQ-E004] - Changing additionalProperties to False for a request parameter
+================================================================================================================
+
+Rationale
+---------
+If the object is defined with additionalProperties set to False then the object will not allow presence of properties not defined on the properties section of the object definition. Changing additionalProperties from True to False makes objects sent from a client, that contain additional properties and were permitted by the "old" Swagger specs, to the server be considered invalid by the backend.
+
+Mitigation
+----------
+A possible mitigation could be to not set additionalProperties to False in the object schema.
+
+Example
+-------
+Old Swagger Specs
+~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: examples/REQ-E004/old.yaml
+   :name: Old Swagger Spec
+   :language: yaml
+   :emphasize-lines: 17-18
+   :linenos:
+
+New Swagger Specs
+~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: examples/REQ-E004/new.yaml
+   :name: New Swagger Spec
+   :language: yaml
+   :linenos:
+
+
+Backward Incompatibility
+~~~~~~~~~~~~~~~~~~~~~~~~
+The following snippet triggers the incompatibility error.
+
+.. literalinclude:: examples/REQ-E004/tester.py
+   :language: py
+   :linenos:
+
+**NOTE**: The code is taking advantage of `bravado <https://github.com/Yelp/bravado>`_

docs/source/rules/examples/REQ-E004/new 2.yaml

@@ -0,0 +1,22 @@
+swagger: '2.0'
+info:
+  title: Minimal Case of REQ-E004 Rule
+  version: '1.0'
+paths:
+  /endpoint:
+    post:
+      parameters:
+      - in: body
+        name: body
+        required: true
+        schema:
+          additionalProperties: false
+          properties:
+            property_1:
+              type: string
+            property_2:
+              type: string
+          type: object
+      responses:
+        default:
+          description: ''

docs/source/rules/examples/REQ-E004/new.yaml

@@ -0,0 +1,22 @@
+swagger: '2.0'
+info:
+  title: Minimal Case of REQ-E004 Rule
+  version: '1.0'
+paths:
+  /endpoint:
+    post:
+      parameters:
+      - in: body
+        name: body
+        required: true
+        schema:
+          additionalProperties: false
+          properties:
+            property_1:
+              type: string
+            property_2:
+              type: string
+          type: object
+      responses:
+        default:
+          description: ''

docs/source/rules/examples/REQ-E004/old 2.yaml

@@ -0,0 +1,21 @@
+swagger: '2.0'
+info:
+  title: Minimal Case of REQ-E004 Rule
+  version: '1.0'
+paths:
+  /endpoint:
+    post:
+      parameters:
+      - in: body
+        name: body
+        required: true
+        schema:
+          properties:
+            property_1:
+              type: string
+            property_2:
+              type: string
+          type: object
+      responses:
+        default:
+          description: ''

docs/source/rules/examples/REQ-E004/old.yaml

@@ -0,0 +1,21 @@
+swagger: '2.0'
+info:
+  title: Minimal Case of REQ-E004 Rule
+  version: '1.0'
+paths:
+  /endpoint:
+    post:
+      parameters:
+      - in: body
+        name: body
+        required: true
+        schema:
+          properties:
+            property_1:
+              type: string
+            property_2:
+              type: string
+          type: object
+      responses:
+        default:
+          description: ''

docs/source/rules/examples/REQ-E004/tester 2.py

@@ -0,0 +1,30 @@
+# -*- coding: utf-8 -*-
+from __future__ import absolute_import
+from __future__ import print_function
+from __future__ import unicode_literals
+
+from os.path import abspath
+
+from bravado.client import SwaggerClient
+from jsonschema import ValidationError
+from six.moves.urllib.parse import urljoin
+from six.moves.urllib.request import pathname2url
+
+old_client = SwaggerClient.from_url(
+    spec_url=urljoin('file:', pathname2url(abspath('old.yaml'))),
+)
+new_client = SwaggerClient.from_url(
+    spec_url=urljoin('file:', pathname2url(abspath('new.yaml'))),
+)
+
+object_to_send = {'property_1': 'v1', 'property_2': 'v2', 'property_3': 'v3'}
+
+print('Calling the post endpoint with the old client: Succeeded')
+old_client.endpoint.post_endpoint(body=object_to_send)
+
+print('Calling the post endpoint with the old client: Failed')
+try:
+    new_client.endpoint.post_endpoint(body=object_to_send)
+    raise RuntimeError('An error was expected')
+except ValidationError:
+    pass

docs/source/rules/examples/REQ-E004/tester.py

@@ -0,0 +1,30 @@
+# -*- coding: utf-8 -*-
+from __future__ import absolute_import
+from __future__ import print_function
+from __future__ import unicode_literals
+
+from os.path import abspath
+
+from bravado.client import SwaggerClient
+from jsonschema import ValidationError
+from six.moves.urllib.parse import urljoin
+from six.moves.urllib.request import pathname2url
+
+old_client = SwaggerClient.from_url(
+    spec_url=urljoin('file:', pathname2url(abspath('old.yaml'))),
+)
+new_client = SwaggerClient.from_url(
+    spec_url=urljoin('file:', pathname2url(abspath('new.yaml'))),
+)
+
+object_to_send = {'property_1': 'v1', 'property_2': 'v2', 'property_3': 'v3'}
+
+print('Calling the post endpoint with the old client: Succeeded')
+old_client.endpoint.post_endpoint(body=object_to_send)
+
+print('Calling the post endpoint with the old client: Failed')
+try:
+    new_client.endpoint.post_endpoint(body=object_to_send)
+    raise RuntimeError('An error was expected')
+except ValidationError:
+    pass

swagger_spec_compatibility/rules/added_enum_value_in_response.py

@@ -12,7 +12,6 @@
 from swagger_spec_compatibility.rules.common import RuleType
 from swagger_spec_compatibility.rules.common import ValidationMessage
 from swagger_spec_compatibility.util import is_path_in_top_level_paths
-from swagger_spec_compatibility.walkers import format_path
 from swagger_spec_compatibility.walkers.enum_values import EnumValuesDifferWalker
 from swagger_spec_compatibility.walkers.response_paths import ResponsePathsWalker
 
@@ -35,4 +34,10 @@ def validate(cls, left_spec, right_spec):
                 continue
             if not is_path_in_top_level_paths(response_paths, enum_values_diff.path):
                 continue
-            yield cls.validation_message(format_path(enum_values_diff.path))
+            message = '\n \t\t{} {}: new enum value {} in property `{}`\n\t\t'.format(
+                enum_values_diff.path[2],
+                enum_values_diff.path[1],
+                enum_values_diff.mapping.new,
+                enum_values_diff.path[-1],
+            )
+            yield cls.validation_message(message)

swagger_spec_compatibility/rules/added_properties_in_response_objects_with_additional_properties_set_to_false.py

@@ -12,7 +12,6 @@
 from swagger_spec_compatibility.rules.common import RuleType
 from swagger_spec_compatibility.rules.common import ValidationMessage
 from swagger_spec_compatibility.util import is_path_in_top_level_paths
-from swagger_spec_compatibility.walkers import format_path
 from swagger_spec_compatibility.walkers.additional_properties import AdditionalPropertiesDifferWalker
 from swagger_spec_compatibility.walkers.additional_properties import DiffType
 from swagger_spec_compatibility.walkers.response_paths import ResponsePathsWalker
@@ -40,4 +39,15 @@ def validate(cls, left_spec, right_spec):
                 continue
             if not is_path_in_top_level_paths(response_paths, additional_properties_diff.path):
                 continue
-            yield cls.validation_message(format_path(additional_properties_diff.path))
+            if additional_properties_diff.properties:
+                message = '\n \t\t{} {}: {}\n\t\t'.format(
+                    additional_properties_diff.path[2],
+                    additional_properties_diff.path[1],
+                    additional_properties_diff.properties.new,
+                )
+            else:
+                message = '\n \t\t{} {}\n\t\t'.format(
+                    additional_properties_diff.path[2],
+                    additional_properties_diff.path[1],
+                )
+            yield cls.validation_message(message)

swagger_spec_compatibility/rules/added_required_property_in_request.py

@@ -12,7 +12,6 @@
 from swagger_spec_compatibility.rules.common import RuleType
 from swagger_spec_compatibility.rules.common import ValidationMessage
 from swagger_spec_compatibility.util import is_path_in_top_level_paths
-from swagger_spec_compatibility.walkers import format_path
 from swagger_spec_compatibility.walkers.request_parameters import RequestParametersWalker
 from swagger_spec_compatibility.walkers.required_properties import RequiredPropertiesDifferWalker
 
@@ -37,4 +36,9 @@ def validate(cls, left_spec, right_spec):
                 continue
             if not is_path_in_top_level_paths(request_parameters_paths, required_property_diff.path):
                 continue
-            yield cls.validation_message(format_path(required_property_diff.path))
+            message = '\n \t\t{} {}: {}\n\t\t'.format(
+                required_property_diff.path[2],
+                required_property_diff.path[1],
+                required_property_diff.mapping.new,
+            )
+            yield cls.validation_message(message)

swagger_spec_compatibility/rules/changed_additional_properties_to_false.py

@@ -0,0 +1,45 @@
+# -*- coding: utf-8 -*-
+from __future__ import absolute_import
+from __future__ import print_function
+from __future__ import unicode_literals
+
+import typing
+
+from bravado_core.spec import Spec
+
+from swagger_spec_compatibility.rules.common import BaseRule
+from swagger_spec_compatibility.rules.common import Level
+from swagger_spec_compatibility.rules.common import RuleType
+from swagger_spec_compatibility.rules.common import ValidationMessage
+from swagger_spec_compatibility.util import is_path_in_top_level_paths
+from swagger_spec_compatibility.walkers.additional_properties import AdditionalPropertiesDifferWalker
+from swagger_spec_compatibility.walkers.additional_properties import DiffType
+from swagger_spec_compatibility.walkers.request_parameters import RequestParametersWalker
+
+
+class ChangedAdditionalPropertiesToFalse(BaseRule):
+    description = \
+        'If the object is defined with additionalProperties set to False then the object will not allow presence of ' \
+        'properties not defined on the properties section of the object definition. ' \
+        'Changing additionalProperties from True to False makes objects sent from a client, ' \
+        'that contain additional properties and were permitted by the "old" Swagger specs, ' \
+        'to the server be considered invalid by the backend.'
+    error_code = 'REQ-E004'
+    error_level = Level.ERROR
+    rule_type = RuleType.REQUEST_CONTRACT
+    short_name = 'Changing additionalProperties to False for a request parameter'
+
+    @classmethod
+    def validate(cls, left_spec, right_spec):
+        # type: (Spec, Spec) -> typing.Iterable[ValidationMessage]
+        request_parameter_paths = RequestParametersWalker(left_spec, right_spec).walk()
+        for additional_properties_diff in AdditionalPropertiesDifferWalker(left_spec, right_spec).walk():
+            if additional_properties_diff.diff_type != DiffType.VALUE:
+                continue
+            if not is_path_in_top_level_paths(request_parameter_paths, additional_properties_diff.path):
+                continue
+            message = "\n \t\t{} {}: schema's additionalProperties changed to False\n\t\t".format(
+                additional_properties_diff.path[2],
+                additional_properties_diff.path[1],
+            )
+            yield cls.validation_message(message)

swagger_spec_compatibility/rules/changed_type.py

@@ -12,7 +12,6 @@
 from swagger_spec_compatibility.rules.common import RuleType
 from swagger_spec_compatibility.rules.common import ValidationMessage
 from swagger_spec_compatibility.util import is_path_in_top_level_paths
-from swagger_spec_compatibility.walkers import format_path
 from swagger_spec_compatibility.walkers.changed_types import ChangedTypesDifferWalker
 from swagger_spec_compatibility.walkers.request_parameters import RequestParametersWalker
 from swagger_spec_compatibility.walkers.response_paths import ResponsePathsWalker
@@ -42,4 +41,11 @@ def validate(cls, left_spec, right_spec):
                 not is_path_in_top_level_paths(response_paths, changed_types_diff.path)
             ):
                 continue
-            yield cls.validation_message(format_path(changed_types_diff.path))
+            message = '\n \t\t{} {}: `{}` changed from `{}` to `{}`\n\t\t'.format(
+                changed_types_diff.path[2],
+                changed_types_diff.path[1],
+                changed_types_diff.path[-1],
+                changed_types_diff.mapping.old,
+                changed_types_diff.mapping.new,
+            )
+            yield cls.validation_message(message)

swagger_spec_compatibility/rules/deleted_endpoint.py

@@ -28,9 +28,11 @@ class DeletedEndpoint(BaseRule):
     def validate(cls, left_spec, right_spec):
         # type: (Spec, Spec) -> typing.Iterable[ValidationMessage]
         endpoints_left_spec = get_endpoints(left_spec)
-        endponts_right_spec = get_endpoints(right_spec)
+        endpoints_right_spec = get_endpoints(right_spec)
 
-        return (
-            cls.validation_message(str(removed_endpoint))
-            for removed_endpoint in endpoints_left_spec - endponts_right_spec
-        )
+        for removed_endpoint in endpoints_left_spec - endpoints_right_spec:
+            message = '{} {} \n\t\t'.format(
+                removed_endpoint.http_verb.value,
+                removed_endpoint.path,
+            )
+            yield cls.validation_message(message)

swagger_spec_compatibility/rules/removed_enum_value_from_request.py

@@ -12,7 +12,6 @@
 from swagger_spec_compatibility.rules.common import RuleType
 from swagger_spec_compatibility.rules.common import ValidationMessage
 from swagger_spec_compatibility.util import is_path_in_top_level_paths
-from swagger_spec_compatibility.walkers import format_path
 from swagger_spec_compatibility.walkers.enum_values import EnumValuesDifferWalker
 from swagger_spec_compatibility.walkers.request_parameters import RequestParametersWalker
 
@@ -37,4 +36,10 @@ def validate(cls, left_spec, right_spec):
                 continue
             if not is_path_in_top_level_paths(request_parameters_paths, enum_values_diff.path):
                 continue
-            yield cls.validation_message(format_path(enum_values_diff.path))
+            message = '\n \t\t{} {}: removed enum value {} in property `{}`\n\t\t'.format(
+                enum_values_diff.path[2],
+                enum_values_diff.path[1],
+                enum_values_diff.mapping.old,
+                enum_values_diff.path[-1],
+            )
+            yield cls.validation_message(message)

swagger_spec_compatibility/rules/removed_properties_from_request_objects_with_additional_properties_set_to_false.py

@@ -12,7 +12,6 @@
 from swagger_spec_compatibility.rules.common import RuleType
 from swagger_spec_compatibility.rules.common import ValidationMessage
 from swagger_spec_compatibility.util import is_path_in_top_level_paths
-from swagger_spec_compatibility.walkers import format_path
 from swagger_spec_compatibility.walkers.additional_properties import AdditionalPropertiesDifferWalker
 from swagger_spec_compatibility.walkers.additional_properties import DiffType
 from swagger_spec_compatibility.walkers.request_parameters import RequestParametersWalker
@@ -40,4 +39,15 @@ def validate(cls, left_spec, right_spec):
                 continue
             if not is_path_in_top_level_paths(request_parameter_paths, additional_properties_diff.path):
                 continue
-            yield cls.validation_message(format_path(additional_properties_diff.path))
+            if additional_properties_diff.properties:
+                message = '\n \t\t{} {}: {}\n\t\t'.format(
+                    additional_properties_diff.path[2],
+                    additional_properties_diff.path[1],
+                    additional_properties_diff.properties.old,
+                )
+            else:
+                message = '\n \t\t{} {}\n\t\t'.format(
+                    additional_properties_diff.path[2],
+                    additional_properties_diff.path[1],
+                )
+            yield cls.validation_message(message)