swagger-spec-compatibility 1.3.4

关于

swagger-spec-compatibility 是一个由Yelp维护的库，提供了自动检测 Swagger/OpenAPI 2.0规范 变更与 向后兼容性 相关的安全性的工具。

swagger-spec-compatibility 的目标是让开发者对其规范变更的安全性有信心，并且使用以前版本的Swagger规范构建的客户端可以继续正确通信。

文档

更多文档可在swagger-spec-compatibility.readthedocs.org找到。

如何安装

# to install the latest released version
$ pip install swagger-spec-compatibility

# to install the latest master [from Github]
$ pip install git+https://github.com/Yelp/swagger-spec-compatibility

示例用法

以下命令假定库已经安装

$ swagger_spec_compatibility -h
usage: swagger_spec_compatibility [-h] {explain,info,run} ...

Tool for the identification of backward incompatible changes between two swagger specs.

The tool provides the following level of results:
- WARNING: the Swagger specs are technically compatible but the are likely to break known Swagger implementations
- ERROR: new Swagger spec does introduce a breaking change respect the old implementation

positional arguments:
  {explain,info,run}  help for sub-command
    explain           explain selected rules
    info              Reports tool's information
    run               run backward compatibility detection

optional arguments:
  -h, --help          show this help message and exit

$ swagger_spec_compatibility explain -r REQ-E001 REQ-E002
Rules explanation
[REQ-E001] Added Required Property in Request contract:
    Adding a required property to an object used in requests leads client request to fail if the property is not present.
[REQ-E002] Removed Enum value from Request contract:
    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.

$ old_spec_path=docs/source/rules/examples/REQ-E001/old.yaml
$ new_spec_path=docs/source/rules/examples/REQ-E001/new.yaml

# Run with all the registered rules
$ swagger_spec_compatibility run ${old_spec_path} ${new_spec_path}
ERROR rules:
    [REQ-E001] Added Required Property in Request contract : #/paths//endpoint/post/parameters/0/schema
$ echo $?
1

# Run with a subset of registered rules
$ swagger_spec_compatibility -r=MIS-E001 -r=MIS-E002 run ${old_spec_path} ${new_spec_path}
$ echo $?
0

$ swagger_spec_compatibility info
swagger-spec-compatibility: 1.3.0
Python version: CPython - 3.6.9
Python compiler: GCC 4.2.1 Compatible Apple LLVM 10.0.1 (clang-1001.0.46.4)
Discovered rules:
    MIS-E001: swagger_spec_compatibility.rules.deleted_endpoint.DeletedEndpoint
    MIS-E002: swagger_spec_compatibility.rules.changed_type.ChangedType
    REQ-E001: swagger_spec_compatibility.rules.added_required_property_in_request.AddedRequiredPropertyInRequest
    REQ-E002: swagger_spec_compatibility.rules.removed_enum_value_from_request.RemovedEnumValueFromRequest
    REQ-E003: swagger_spec_compatibility.rules.removed_properties_from_request_objects_with_additional_properties_set_to_false.RemovedPropertiesFromRequestObjectsWithAdditionalPropertiesSetToFalse
    RES-E001: swagger_spec_compatibility.rules.added_properties_in_response_objects_with_additional_properties_set_to_false.AddedPropertiesInResponseObjectsWithAdditionalPropertiesSetToFalse
    RES-E002: swagger_spec_compatibility.rules.removed_required_property_from_response.RemovedRequiredPropertyFromResponse
    RES-E003: swagger_spec_compatibility.rules.added_enum_value_in_response.AddedEnumValueInRequest

开发

代码使用Sphinx进行文档化。

virtualenv建议用于保持依赖项和库的隔离。

# Initialize your dev environment
$ make minimal

# Ensure that you have activated the virtualenvironment
$ source ./venv/bin/activate

许可

版权所有 2019 Yelp, Inc。

Swagger Spec Compatibility采用Apache License 2.0许可。