Skip to main content

Python library to check Swagger Spec backward compatibility

Project description

https://img.shields.io/travis/com/Yelp/swagger-spec-compatibility.svg https://img.shields.io/codecov/c/gh/Yelp/swagger-spec-compatibility.svg PyPi version Supported Python versions

swagger-spec-compatibility

About

swagger-spec-compatibility is a Yelp maintained library that provides tools to automatically detect the safety of Swagger/OpenAPI 2.0 specification changes with respect to backwards compatibility.

swagger-spec-compatibility aims to give developers confidence that their spec changes are safe and that clients built with previous versions of the Swagger spec can continue to communicate correctly.

Documentation

More documentation is available at swagger-spec-compatibility.readthedocs.org.

How to Install

# 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

Example Usage

The commands below assume that the library is already installed

$ 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}         help for 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

Development

Code is documented using Sphinx.

virtualenv is recommended to keep dependencies and libraries isolated.

Setup

# Initialize your dev environment
$ make minimal

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

Tip: If you have aactivator installed the virtual environment will be automatically activated

How to define a new compatibility rule

Use the following steps to define a new rule:

  1. Define a new rule class in swagger_spec_compatibility/rules/

# Example of the file content  (assume that the file will be named FILE.py)
class RuleClassName(BaseRule):
    description = ''
    error_code = 'ERROR_CODE'
    error_level = Level.LEVEL
    rule_type = RuleType.TYPE
    short_name = ''

    @classmethod
    def validate(cls, left_spec, right_spec):
        # type: (Spec, Spec) -> typing.Iterable[ValidationMessage]
        # Implement here your logic
        raise NotImplemented()

 # 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`
  1. Add import into swagger_spec_compatibllity/rules/__init__.py to allow rule discovery

from swagger_spec_compatibility.rules.FILE import RuleClassName  # noqa: F401
  1. Add tests to ensure that your rule behaves as expected (tests in tests/rules/FILE_test.py)

  2. Add documentation for the defined rule in docs/source/rules/ERROR_CODE.rst. Try to be consistent with the style of the others documentation pages

  3. Add example of a Swagger spec change that triggers the rule in docs/source/rules/examples/ERROR_CODE.rst. Ensure to define a tester.py file that will make explicit the backward incompatible change through the usage of a bravado client (check the other testers for examples). NOTE: The testers are executed by automated tests, this is intended to ensure that documentation is in sync with the codebase.

Contributing

  1. Fork it ( http://github.com/Yelp/swagger-spec-compatibility/fork )

  2. Create your feature branch (git checkout -b my-new-feature)

  3. Add your modifications

  4. Commit your changes (git commit -m "Add some feature")

  5. Push to the branch (git push origin my-new-feature)

  6. Create new Pull Request

License

Copyright 2019 Yelp, Inc.

Swagger Spec Compatibility is licensed with a Apache License 2.0.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

swagger-spec-compatibility-1.0.1.tar.gz (19.2 kB view details)

Uploaded Source

Built Distribution

swagger_spec_compatibility-1.0.1-py2.py3-none-any.whl (36.7 kB view details)

Uploaded Python 2Python 3

File details

Details for the file swagger-spec-compatibility-1.0.1.tar.gz.

File metadata

  • Download URL: swagger-spec-compatibility-1.0.1.tar.gz
  • Upload date:
  • Size: 19.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.12.1 pkginfo/1.5.0.1 requests/2.21.0 setuptools/40.6.2 requests-toolbelt/0.9.1 tqdm/4.31.1 CPython/3.7.2

File hashes

Hashes for swagger-spec-compatibility-1.0.1.tar.gz
Algorithm Hash digest
SHA256 41985ef830c83f74cbb51f7037fdeee4f7e7bff79a920d051087f760b6d612f9
MD5 286cf736bf44c9125945b4fdbcb1439c
BLAKE2b-256 efbc57b0a954c6a434303e64dbbdb54ab9037546f6fee0705431757ca8c84802

See more details on using hashes here.

File details

Details for the file swagger_spec_compatibility-1.0.1-py2.py3-none-any.whl.

File metadata

  • Download URL: swagger_spec_compatibility-1.0.1-py2.py3-none-any.whl
  • Upload date:
  • Size: 36.7 kB
  • Tags: Python 2, Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.12.1 pkginfo/1.5.0.1 requests/2.21.0 setuptools/40.6.2 requests-toolbelt/0.9.1 tqdm/4.31.1 CPython/3.7.2

File hashes

Hashes for swagger_spec_compatibility-1.0.1-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 9c22df6cdef17bcf461e2fee4a4c7981159f9301f1a7203632393650eb61c3bb
MD5 c489f27eca0920ccb6471354b35f30c6
BLAKE2b-256 41fb07893b8f25451982cff570c6d0f9e06deb64f7887cc6a29a377f47681470

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page