[WIP] Add rules for nullable cases

docs/source/rules/REQ-E004.rst

@@ -0,0 +1,39 @@
+[REQ-E004] - TODO
+=====================================================
+
+Rationale
+---------
+TODO
+
+Mitigation
+----------
+TODO
+
+Example
+-------
+Old Swagger Specs
+~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: examples/REQ-E004/old.yaml
+   :name: Old Swagger Spec
+   :language: yaml
+   :linenos:
+   :emphasize-lines: 17
+
+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/RES-E004.rst

@@ -0,0 +1,39 @@
+[RES-E004] - TODO
+=====================================================
+
+Rationale
+---------
+TODO
+
+Mitigation
+----------
+TODO
+
+Example
+-------
+Old Swagger Specs
+~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: examples/RES-E004/old.yaml
+   :name: Old Swagger Spec
+   :language: yaml
+   :linenos:
+
+New Swagger Specs
+~~~~~~~~~~~~~~~~~
+
+.. literalinclude:: examples/RES-E004/new.yaml
+   :name: New Swagger Spec
+   :language: yaml
+   :linenos:
+   :emphasize-lines: 16
+
+Backward Incompatibility
+~~~~~~~~~~~~~~~~~~~~~~~~
+The following snippet triggers the incompatibility error.
+
+.. literalinclude:: examples/RES-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.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:
+              type: string
+          required:
+          - property
+          type: object
+      responses:
+        default:
+          description: ''

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

@@ -0,0 +1,23 @@
+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:
+              type: string
+              x-nullable: true
+          required:
+          - property
+          type: object
+      responses:
+        default:
+          description: ''

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 bravado_core.exception import SwaggerError
+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': None}
+
+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: Succeeded')
+try:
+    new_client.endpoint.post_endpoint(body=object_to_send)
+    raise RuntimeError('An error was expected')
+except SwaggerError:
+    pass

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

@@ -0,0 +1,20 @@
+swagger: '2.0'
+info:
+  title: Minimal Case of RES-E004 Rule
+  version: '1.0'
+definitions: {}
+paths:
+  /endpoint:
+    get:
+      responses:
+        default:
+          description: ''
+          schema:
+            properties:
+              property:
+                type: string
+                x-nullable: true
+            required:
+            - property
+            type: object
+            x-model: get_endpoint_response

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

@@ -0,0 +1,19 @@
+swagger: '2.0'
+info:
+  title: Minimal Case of RES-E004 Rule
+  version: '1.0'
+definitions: {}
+paths:
+  /endpoint:
+    get:
+      responses:
+        default:
+          description: ''
+          schema:
+            properties:
+              property:
+                type: string
+            required:
+            - property
+            type: object
+            x-model: get_endpoint_response

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

@@ -0,0 +1,39 @@
+# -*- 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 bravado_core.validate import validate_schema_object
+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_validate = {'property': None}
+
+print('Validating the get endpoint response with the old client: Failed')
+try:
+    validate_schema_object(
+        swagger_spec=old_client.swagger_spec,
+        schema_object_spec=old_client.swagger_spec.definitions['get_endpoint_response']._model_spec,
+        value=object_to_validate,
+    )
+    raise RuntimeError('An error was expected')
+except ValidationError:
+    pass
+
+print('Validating the get endpoint response with the new client: Succeeded')
+validate_schema_object(
+    swagger_spec=new_client.swagger_spec,
+    schema_object_spec=new_client.swagger_spec.definitions['get_endpoint_response']._model_spec,
+    value=object_to_validate,
+)

docs/source/rules/index.rst

@@ -10,6 +10,7 @@ Request Contract Changes
    REQ-E001
    REQ-E002
    REQ-E003
+   REQ-E004
 
 Response Contract Changes
 -------------------------
@@ -20,6 +21,7 @@ Response Contract Changes
    RES-E001
    RES-E002
    RES-E003
+   RES-E004
 
 Miscellaneous Changes
 ---------------------

docs/source/swagger_spec_compatibility.rst

@@ -102,6 +102,16 @@ swagger_spec_compatibility Package
     :undoc-members:
     :show-inheritance:
 
+.. automodule:: swagger_spec_compatibility.rules.removed_nullable_property_from_request
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+.. automodule:: swagger_spec_compatibility.rules.added_nullable_property_in_response
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 :mod:`spec_utils` Module
 ------------------------
 
@@ -136,6 +146,11 @@ swagger_spec_compatibility Package
     :undoc-members:
     :show-inheritance:
 
+.. automodule:: swagger_spec_compatibility.walkers.changed_xnullable
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
 .. automodule:: swagger_spec_compatibility.walkers.enum_values
     :members:
     :undoc-members:

swagger_spec_compatibility/rules/added_nullable_property_in_response.py

@@ -0,0 +1,38 @@
+# -*- 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 import format_path
+from swagger_spec_compatibility.walkers.changed_xnullable import ChangedXNullableDifferWalker
+from swagger_spec_compatibility.walkers.response_paths import ResponsePathsWalker
+
+
+class AddedNullablePropertyInResponse(BaseRule):
+    description = 'TODO'
+    error_code = 'RES-E004'
+    error_level = Level.ERROR
+    rule_type = RuleType.RESPONSE_CONTRACT
+    short_name = 'TODO'
+    documentation_link = None
+
+    @classmethod
+    def validate(cls, left_spec, right_spec):
+        # type: (Spec, Spec) -> typing.Iterable[ValidationMessage]
+        response_paths = ResponsePathsWalker(left_spec, right_spec).walk()
+
+        for nullable_values_diff in ChangedXNullableDifferWalker(left_spec, right_spec).walk():
+            if not nullable_values_diff.mapping.new:
+                continue
+            if not is_path_in_top_level_paths(response_paths, nullable_values_diff.path):
+                continue
+            yield cls.validation_message(format_path(nullable_values_diff.path))

swagger_spec_compatibility/rules/removed_nullable_property_from_request.py

@@ -0,0 +1,39 @@
+# -*- 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 import format_path
+from swagger_spec_compatibility.walkers.changed_xnullable import ChangedXNullableDifferWalker
+from swagger_spec_compatibility.walkers.request_parameters import RequestParametersWalker
+
+
+class RemovedNullablePropertyFromRequest(BaseRule):
+    description = 'TODO'
+    error_code = 'REQ-E004'
+    error_level = Level.ERROR
+    rule_type = RuleType.REQUEST_CONTRACT
+    short_name = 'TODO'
+    documentation_link = None
+
+    @classmethod
+    def validate(cls, left_spec, right_spec):
+        # type: (Spec, Spec) -> typing.Iterable[ValidationMessage]
+        request_parameters_paths = RequestParametersWalker(left_spec, right_spec).walk()
+
+        # FIXME: the used walker is not able to merge together parameters defined in different locations
+        for nullable_values_diff in ChangedXNullableDifferWalker(left_spec, right_spec).walk():
+            if not nullable_values_diff.mapping.old:
+                continue
+            if not is_path_in_top_level_paths(request_parameters_paths, nullable_values_diff.path):
+                continue
+            yield cls.validation_message(format_path(nullable_values_diff.path))