swagger_spec_compatibility Package¶
swagger_spec_compatibility
Package¶
cache
Module¶
cli
Module¶
-
class
swagger_spec_compatibility.cli.common.
CLIProtocol
(*args, **kwargs)[source]¶ Bases:
typing_extensions.Protocol
-
command
= None¶
-
func
= None¶
-
rules
Module¶
-
swagger_spec_compatibility.rules.
compatibility_status
(old_spec, new_spec, rules=<swagger_spec_compatibility.rules._ALL_RULES object>)[source]¶
-
class
swagger_spec_compatibility.rules.added_properties_in_response_objects_with_additional_properties_set_to_false.
AddedPropertiesInResponseObjectsWithAdditionalPropertiesSetToFalse
[source]¶ Bases:
swagger_spec_compatibility.rules.common.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. Adding a definition of a new property makes object sent from the server to the client be considered invalid by a client that is using "old" Swagger specs.'¶
-
error_code
= 'RES-E001'¶
-
error_level
= 2¶
-
rule_type
= 1¶
-
short_name
= 'Added properties in an object with additionalProperties set to False used in response'¶
-
-
class
swagger_spec_compatibility.rules.added_required_property_in_request.
AddedRequiredPropertyInRequest
[source]¶ Bases:
swagger_spec_compatibility.rules.common.BaseRule
-
description
= 'Adding a required property to an object used in requests leads client request to fail if the property is not present.'¶
-
error_code
= 'REQ-E001'¶
-
error_level
= 2¶
-
rule_type
= 0¶
-
short_name
= 'Added Required Property in Request contract'¶
-
-
class
swagger_spec_compatibility.rules.added_enum_value_in_response.
AddedEnumValueInRequest
[source]¶ Bases:
swagger_spec_compatibility.rules.common.BaseRule
-
description
= 'Adding an enum value to a response parameter is backward incompatible as clients, using the "old" version of the Swagger specs, will not be able to properly validate the response.'¶
-
error_code
= 'RES-E003'¶
-
error_level
= 2¶
-
rule_type
= 1¶
-
short_name
= 'Added Enum value in Response contract'¶
-
-
class
swagger_spec_compatibility.rules.common.
BaseRule
[source]¶ Bases:
object
-
description
= None¶
-
documentation_link
= None¶
-
error_code
= None¶
-
error_level
= None¶
-
rule_type
= None¶
-
short_name
= None¶
-
-
class
swagger_spec_compatibility.rules.common.
Level
[source]¶ Bases:
enum.IntEnum
An enumeration.
-
ERROR
= 2¶
-
INFO
= 0¶
-
WARNING
= 1¶
-
-
class
swagger_spec_compatibility.rules.common.
RuleProtocol
(*args, **kwargs)[source]¶ Bases:
typing_extensions.Protocol
-
description
= None¶
-
documentation_link
= None¶
-
error_code
= None¶
-
error_level
= None¶
-
rule_type
= None¶
-
short_name
= None¶
-
-
class
swagger_spec_compatibility.rules.common.
RuleRegistry
[source]¶ Bases:
abc.ABCMeta
-
class
swagger_spec_compatibility.rules.common.
RuleType
[source]¶ Bases:
enum.IntEnum
An enumeration.
-
MISCELLANEOUS
= 2¶
-
REQUEST_CONTRACT
= 0¶
-
RESPONSE_CONTRACT
= 1¶
-
-
class
swagger_spec_compatibility.rules.common.
ValidationMessage
[source]¶ Bases:
swagger_spec_compatibility.rules.common._ValidationMessage
-
swagger_spec_compatibility.rules.common.
get_rule_documentation_link
(rule)[source]¶ Helper method that allows to extract documentation link related to a given rule.
If the rule is implemented within swagger-spec-compatibility library then the documentation link will fall back to the “default” read-the-docs link
-
class
swagger_spec_compatibility.rules.deleted_endpoint.
DeletedEndpoint
[source]¶ Bases:
swagger_spec_compatibility.rules.common.BaseRule
-
description
= 'An endpoint has been removed. This change is not backward compatible as holders of stale swagger specs (like old mobile Apps) could continue to call the removed endpoint and this will cause an HTTP error status code (usually an HTTP/400 or HTTP/404)'¶
-
error_code
= 'MIS-E001'¶
-
error_level
= 2¶
-
rule_type
= 2¶
-
short_name
= 'Delete Endpoint'¶
-
-
class
swagger_spec_compatibility.rules.changed_type.
ChangedType
[source]¶ Bases:
swagger_spec_compatibility.rules.common.BaseRule
-
description
= 'Changing the type of a field is not backward compatible as a client using "old" Swagger specs will send the field with a different type leading the service to fail to validate the request. On the other end, if the object containing the updated field is used in the response, it will lead to unexpected client errors when parsing the response and/or using the updated property.'¶
-
error_code
= 'MIS-E002'¶
-
error_level
= 2¶
-
rule_type
= 2¶
-
short_name
= 'Changed type'¶
-
-
class
swagger_spec_compatibility.rules.removed_enum_value_from_request.
RemovedEnumValueFromRequest
[source]¶ Bases:
swagger_spec_compatibility.rules.common.BaseRule
-
description
= 'Removing an enum value from a request parameter is backward incompatible as a previously valid request will not be valid. This happens because a request containing the removed enum value, valid according to the "old" Swagger spec, is not valid according to the new specs.'¶
-
error_code
= 'REQ-E002'¶
-
error_level
= 2¶
-
rule_type
= 0¶
-
short_name
= 'Removed Enum value from Request contract'¶
-
-
class
swagger_spec_compatibility.rules.removed_properties_from_request_objects_with_additional_properties_set_to_false.
RemovedPropertiesFromRequestObjectsWithAdditionalPropertiesSetToFalse
[source]¶ Bases:
swagger_spec_compatibility.rules.common.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. Removing a definition of an existing property makes objects sent from a client, that is using "old" Swagger specs, to the server be considered invalid by the backend.'¶
-
error_code
= 'REQ-E003'¶
-
error_level
= 2¶
-
rule_type
= 0¶
-
short_name
= 'Removing properties from an object with additionalProperties set to False used as request parameter'¶
-
-
class
swagger_spec_compatibility.rules.removed_required_property_from_response.
RemovedRequiredPropertyFromResponse
[source]¶ Bases:
swagger_spec_compatibility.rules.common.BaseRule
-
description
= 'Removing a required property from an object leads to false expectation on the client receiving the object. If the client is using "old" service\'s Swagger spec it will expect the property to be present and so it could throw errors. It could be valid to assume that the client won\'t perform response validation and this to unexpected errors while parsing the response and/or using the missing property.'¶
-
error_code
= 'RES-E002'¶
-
error_level
= 2¶
-
rule_type
= 1¶
-
short_name
= 'Removed Required Property from Response contract'¶
-
spec_utils
Module¶
-
class
swagger_spec_compatibility.spec_utils.
Endpoint
[source]¶ Bases:
swagger_spec_compatibility.spec_utils._Endpoint
-
class
swagger_spec_compatibility.spec_utils.
HTTPVerb
[source]¶ Bases:
enum.Enum
An enumeration.
-
DELETE
= 'delete'¶
-
GET
= 'get'¶
-
HEAD
= 'head'¶
-
OPTIONS
= 'options'¶
-
PARAMETERS
= 'parameters'¶
-
PATCH
= 'patch'¶
-
POST
= 'post'¶
-
PUT
= 'put'¶
-
-
class
swagger_spec_compatibility.spec_utils.
StatusCodeSchema
(status_code, mapping)¶ Bases:
tuple
-
mapping
¶ Alias for field number 1
-
status_code
¶ Alias for field number 0
-
util
Module¶
-
class
swagger_spec_compatibility.util.
EntityMapping
(old, new)[source]¶ Bases:
typing.Generic
-
new
¶
-
old
¶
-
walkers
Module¶
-
class
swagger_spec_compatibility.walkers.
SchemaWalker
(left_spec, right_spec, **kwargs)[source]¶ Bases:
swagger_spec_compatibility.walkers.Walker
Walker aware of how a Swagger schema looks like.
The main difference between this walker and Walker is that this walker keeps in consideration some peculiarity of the swagger specs.
The walker implementation should never worry about dereferencing as the traversing is performed on the fully flattened and dereferenced specs
-
fix_parameter_path
(path, original_path, value)[source]¶ Fix an eventual path present on the value returned by the walker.
The SwaggerAwareWalker modifies the indexing approach used for parameters due to the fact that parameters are defined as arrays and modifying their order would not change the semantic.
-
-
class
swagger_spec_compatibility.walkers.
Walker
(left, right, **kwargs)[source]¶ Bases:
typing.Generic
Generic Walker over two objects.
The abstract class strips away the details related to dictionary vs list iterations, path update etc.
-
dict_check
(path, left_dict, right_dict)[source]¶ Compare the left and right content of path in case both objects are dictionaries.
-
list_check
(path, left_list, right_list)[source]¶ Compare the left and right content of path in case both objects are list.
-
should_path_be_walked_through
(path)[source]¶ Determine whether to traverse or interrupt traversal of a given path.
This method allows Walkers to skip traversal of area of the specs that are “not interesting”. This will allow to write simpler methods and to avoid needless traversing of the Specs.
-
-
class
swagger_spec_compatibility.walkers.additional_properties.
AdditionalPropertiesDiff
[source]¶ Bases:
swagger_spec_compatibility.walkers.additional_properties.AdditionalPropertiesDiff
-
class
swagger_spec_compatibility.walkers.additional_properties.
AdditionalPropertiesDifferWalker
(left_spec, right_spec, **kwargs)[source]¶ Bases:
swagger_spec_compatibility.walkers.SchemaWalker
-
additionalPropertiesValue
= None¶
-
dict_check
(path, left_dict, right_dict)[source]¶ Compare the left and right content of path in case both objects are dictionaries.
-
diffs
= None¶
-
left_spec
= None¶
-
list_check
(path, left_list, right_list)[source]¶ Compare the left and right content of path in case both objects are list.
-
right_spec
= None¶
-
-
class
swagger_spec_compatibility.walkers.additional_properties.
DiffType
[source]¶ Bases:
enum.Enum
An enumeration.
-
PROPERTIES
= 0¶
-
VALUE
= 1¶
-
-
class
swagger_spec_compatibility.walkers.changed_types.
ChangedTypesDiff
[source]¶ Bases:
swagger_spec_compatibility.walkers.changed_types.ChangedTypesDiff
-
class
swagger_spec_compatibility.walkers.changed_types.
ChangedTypesDifferWalker
(left_spec, right_spec)[source]¶ Bases:
swagger_spec_compatibility.walkers.SchemaWalker
-
dict_check
(path, left_dict, right_dict)[source]¶ Compare the left and right content of path in case both objects are dictionaries.
-
diffs
= None¶
-
left_spec
= None¶
-
list_check
(path, left_list, right_list)[source]¶ Compare the left and right content of path in case both objects are list.
-
right_spec
= None¶
-
-
class
swagger_spec_compatibility.walkers.enum_values.
EnumValuesDiff
[source]¶ Bases:
swagger_spec_compatibility.walkers.enum_values.EnumValuesDiff
-
class
swagger_spec_compatibility.walkers.enum_values.
EnumValuesDifferWalker
(left_spec, right_spec, **kwargs)[source]¶ Bases:
swagger_spec_compatibility.walkers.SchemaWalker
-
dict_check
(path, left_dict, right_dict)[source]¶ Compare the left and right content of path in case both objects are dictionaries.
-
left_spec
= None¶
-
list_check
(path, left_list, right_list)[source]¶ Compare the left and right content of path in case both objects are list.
-
right_spec
= None¶
-
-
class
swagger_spec_compatibility.walkers.request_parameters.
RequestParametersWalker
(left_spec, right_spec)[source]¶ Bases:
swagger_spec_compatibility.walkers.SchemaWalker
-
dict_check
(path, left_dict, right_dict)[source]¶ Compare the left and right content of path in case both objects are dictionaries.
-
fix_parameter_path
(path, original_path, value)[source]¶ Fix an eventual path present on the value returned by the walker.
The SwaggerAwareWalker modifies the indexing approach used for parameters due to the fact that parameters are defined as arrays and modifying their order would not change the semantic.
-
left_spec
= None¶
-
list_check
(path, left_list, right_list)[source]¶ Compare the left and right content of path in case both objects are list.
-
right_spec
= None¶
-
-
class
swagger_spec_compatibility.walkers.required_properties.
RequiredPropertiesDiff
[source]¶ Bases:
swagger_spec_compatibility.walkers.required_properties.RequiredPropertiesDiff
-
class
swagger_spec_compatibility.walkers.required_properties.
RequiredPropertiesDifferWalker
(left_spec, right_spec)[source]¶ Bases:
swagger_spec_compatibility.walkers.SchemaWalker
-
dict_check
(path, left_dict, right_dict)[source]¶ Compare the left and right content of path in case both objects are dictionaries.
-
diffs
= None¶
-
left_spec
= None¶
-
list_check
(path, left_list, right_list)[source]¶ Compare the left and right content of path in case both objects are list.
-
right_spec
= None¶
-
-
class
swagger_spec_compatibility.walkers.response_paths.
ResponsePathsWalker
(left_spec, right_spec)[source]¶ Bases:
swagger_spec_compatibility.walkers.SchemaWalker
-
dict_check
(path, left_dict, right_dict)[source]¶ Compare the left and right content of path in case both objects are dictionaries.
-
left_spec
= None¶
-
list_check
(path, left_list, right_list)[source]¶ Compare the left and right content of path in case both objects are list.
-
paths
= None¶
-
right_spec
= None¶
-