swagger-spec-compatibility 1.2.0

关于

swagger-spec-compatibility是一个yelp维护的库，它提供了自动检测的工具 Swagger/OpenAPI 2.0 specification变化的安全性 关于向后兼容性。

swagger-spec-compatibility旨在让开发人员确信他们的规范更改是安全的，并且客户机 使用以前版本的swagger规范构建的系统可以继续正常通信。

文件

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

如何安装

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

# 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][-r {MIS-E001,MIS-E002,REQ-E001,REQ-E002,REQ-E003,RES-E001,RES-E002,RES-E003}[{MIS-E001,MIS-E002,REQ-E001,REQ-E002,REQ-E003,RES-E001,RES-E002,RES-E003} ...]]{explain,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,run}helpfor sub-command
    explain             explain selected rules
    run                 run backward compatibility detection

optional arguments:
  -h, --help            show this help message and exit
  -r {MIS-E001,MIS-E002,REQ-E001,REQ-E002,REQ-E003,RES-E001,RES-E002,RES-E003}[{MIS-E001,MIS-E002,REQ-E001,REQ-E002,REQ-E003,RES-E001,RES-E002,RES-E003} ...], --rules {MIS-E001,MIS-E002,REQ-E001,REQ-E002,REQ-E003,RES-E001,RES-E002,RES-E003}[{MIS-E001,MIS-E002,REQ-E001,REQ-E002,REQ-E003,RES-E001,RES-E002,RES-E003} ...]
                        Rules to apply for compatibility detection. (default:
                        ['MIS-E001', 'MIS-E002', 'REQ-E001', 'REQ-E002',
                        'REQ-E003', 'RES-E001', 'RES-E002', 'RES-E003'])

$ swagger_spec_compatibility explain -r=REQ-E001 -r=REQ-E002 explain
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

发展

使用Sphinx记录代码。

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

# Initialize your dev environment
$ make minimal

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

# Example of the file content  (assume that the file will be named FILE.py)classRuleClassName(BaseRule):description=''error_code='ERROR_CODE'error_level=Level.LEVELrule_type=RuleType.TYPEshort_name=''@classmethoddefvalidate(cls,left_spec,right_spec):# type: (Spec, Spec) -> typing.Iterable[ValidationMessage]# Implement here your logicraiseNotImplemented()# Please make sure that:#  * `description` and `short_name` are reasonably explicative to support `swagger_spec_compatibility explain` command#  * `error_code` has REQ- prefix for `RuleType.REQUEST_CONTRACT`, RES- for `RuleType.RESPONSE_CONTRACT` and MIS- for `RuleType.MISCELLANEOUS`

许可证

版权所有2019 Yelp，Inc.

swagger规范的兼容性是由Apache License 2.0授权的。