swagger_spec_compatibility Package

cache Module

class swagger_spec_compatibility.cache.typed_lru_cache(maxsize=None)[source]

Bases: object

cached_function
maxsize
uncached_function

cli Module

swagger_spec_compatibility.cli.parser()[source]
class swagger_spec_compatibility.cli.common.CLIProtocol(*args, **kwargs)[source]

Bases: typing_extensions.Protocol

command = None
func = None
class swagger_spec_compatibility.cli.common.CLIRulesProtocol(*args, **kwargs)[source]

Bases: typing_extensions.Protocol

blacklist_rules = None
rules = None
swagger_spec_compatibility.cli.common.add_rule_discovery_argument(argument_parser)[source]
swagger_spec_compatibility.cli.common.add_rules_arguments(argument_parser)[source]
swagger_spec_compatibility.cli.common.cli_rules()[source]
swagger_spec_compatibility.cli.common.post_process_rules_cli_arguments(args)[source]
swagger_spec_compatibility.cli.common.pre_process_cli_to_discover_rules(argv=None)[source]
swagger_spec_compatibility.cli.common.rules(cli_args)[source]
swagger_spec_compatibility.cli.common.uri(param)[source]
swagger_spec_compatibility.cli.explain.add_sub_parser(subparsers)[source]
swagger_spec_compatibility.cli.explain.execute(cli_args)[source]
swagger_spec_compatibility.cli.info.add_sub_parser(subparsers)[source]
swagger_spec_compatibility.cli.info.execute(cli_args)[source]
swagger_spec_compatibility.cli.run.add_sub_parser(subparsers)[source]
swagger_spec_compatibility.cli.run.execute(cli_args)[source]

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'
classmethod validate(left_spec, right_spec)[source]
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'
classmethod validate(left_spec, right_spec)[source]
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'
classmethod validate(left_spec, right_spec)[source]
class swagger_spec_compatibility.rules.common.BaseRule[source]

Bases: object

description = None
error_code = None
error_level = None
classmethod explain()[source]
rule_type = None
short_name = None
classmethod validate(left_spec, right_spec)[source]
classmethod validation_message(reference)[source]
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
error_code = None
error_level = None
rule_type = None
short_name = None
classmethod validate(left_spec, right_spec)[source]
class swagger_spec_compatibility.rules.common.RuleRegistry[source]

Bases: abc.ABCMeta

static has_rule(rule_name)[source]
static rule(rule_name)[source]
static rule_names()[source]
static rules()[source]
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

json_representation()[source]
string_representation()[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'
classmethod validate(left_spec, right_spec)[source]
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'
classmethod validate(left_spec, right_spec)[source]
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'
classmethod validate(left_spec, right_spec)[source]
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'
classmethod validate(left_spec, right_spec)[source]
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'
classmethod validate(left_spec, right_spec)[source]

spec_utils Module

class swagger_spec_compatibility.spec_utils.Endpoint[source]

Bases: swagger_spec_compatibility.spec_utils._Endpoint

static from_swagger_operation(operation)[source]
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'
from_swagger_operation = <function HTTPVerb.from_swagger_operation>[source]
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

swagger_spec_compatibility.spec_utils.get_endpoints[source]
swagger_spec_compatibility.spec_utils.get_operation_mappings(old_spec, new_spec)[source]
swagger_spec_compatibility.spec_utils.get_operations[source]
swagger_spec_compatibility.spec_utils.get_properties(swagger_spec, schema)[source]
swagger_spec_compatibility.spec_utils.get_required_properties(swagger_spec, schema)[source]
swagger_spec_compatibility.spec_utils.iterate_on_responses_status_codes(old_operation, new_operation)[source]
swagger_spec_compatibility.spec_utils.load_spec_from_spec_dict(spec_dict)[source]
swagger_spec_compatibility.spec_utils.load_spec_from_uri[source]

util Module

class swagger_spec_compatibility.util.EntityMapping(old, new)[source]

Bases: typing.Generic

new
old
swagger_spec_compatibility.util.is_path_in_top_level_paths(top_level_paths, path)[source]
swagger_spec_compatibility.util.wrap(text, width=120, indent='')[source]

walkers Module

class swagger_spec_compatibility.walkers.NoValue[source]

Bases: object

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.

value_check(path, left_value, right_value)[source]

Compare the left and right content of path in case the objects have different types or are not dictionaries or lists.

walk()[source]

Fully traverse the left and right objects. NOTE: the traversing is internally cached such that all the subsequent calls

to walk() are equivalent to an attribute access
swagger_spec_compatibility.walkers.format_path(path)[source]
class swagger_spec_compatibility.walkers.additional_properties.AdditionalPropertiesDiff[source]

Bases: swagger_spec_compatibility.walkers.additional_properties.AdditionalPropertiesDiff

fix_parameter_path(path, original_path)[source]
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
value_check(path, left_value, right_value)[source]

Compare the left and right content of path in case the objects have different types or are not dictionaries or lists.

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

fix_parameter_path(path, original_path)[source]
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
value_check(path, left_value, right_value)[source]

Compare the left and right content of path in case the objects have different types or are not dictionaries or lists.

class swagger_spec_compatibility.walkers.enum_values.EnumValuesDiff[source]

Bases: swagger_spec_compatibility.walkers.enum_values.EnumValuesDiff

fix_parameter_path(path, original_path)[source]
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
value_check(path, left_value, right_value)[source]

Compare the left and right content of path in case the objects have different types or are not dictionaries or lists.

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
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.

value_check(path, left_value, right_value)[source]

Compare the left and right content of path in case the objects have different types or are not dictionaries or lists.

class swagger_spec_compatibility.walkers.required_properties.RequiredPropertiesDiff[source]

Bases: swagger_spec_compatibility.walkers.required_properties.RequiredPropertiesDiff

fix_parameter_path(path, original_path)[source]
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
value_check(path, left_value, right_value)[source]

Compare the left and right content of path in case the objects have different types or are not dictionaries or lists.

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
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.

value_check(path, left_value, right_value)[source]

Compare the left and right content of path in case the objects have different types or are not dictionaries or lists.