Swagger::Diff

You can tell me by the way I walk - Genesis

Swagger::Diff is a utility for comparing two different Open API Initiative (OAI) specifications (fka Swagger specifications). Its intended use is to determine whether a newer API specification is backwards-compatible with an older API specification. It provides both an RSpec matcher and helper functions that can be used directly. Specifications are considered backwards compatible if:

• all path and verb combinations in the old specification are present in the new one
• no request parameters are required in the new specification that were not required in the old one
• all request parameters in the old specification are present in the new one
• all request parameters in the old specification have the same type in the new one
• all response attributes in the old specification are present in the new one
• all response attributes in the old specification have the same type in the new one

It can also be used to enumerate all changes between two specifications (i.e., to generate a changelog).

Read more on the Civis Analytics blog.

Installation

Add this line to your application's Gemfile:

gem'swagger-diff'

And then execute:

$ bundle

Or install it yourself as:

$ gem install swagger-diff

Usage

OAI specifications can be any valid OAI file format, raw or parsed:

• the path to a file containing an OAI specification. This may be local (e.g., /path/to/specification.json) or remote (e.g., http://host.domain/specification.yml)
• a Hash containing a parsed OAI specification (e.g., the output of JSON.parse)
• a string of JSON containing an OAI specification
• a string of YAML containing an OAI specification

RSpec

expect(<new>).tobe_compatible_with(<old>)

If new is incompatible with old, the spec will fail and print a list of backwards-incompatibilities.

Direct Invocation

If you are not using RSpec, you can directly invoke the comparison function:

diff=Swagger::Diff::Diff.new(<old>, <new>)diff.compatible?

It will return true if new is compatible with old, false otherwise. #incompatibilities will return a hash containing the incompatible endpoints, request parameters, and response attributes; e.g.,

{endpoints: ['put /a/{}'],request_params: {'get /a/'=>['missing request param: limit (in: query, type: integer)'],'post /a/'=>['new required request param: extra'],'put /b/{}'=>['new required request param: extra']},response_attributes: {'post /a/'=>['missing attribute from 200 response: description (in: body, type: string)'],'get /a/{}'=>['missing attribute from 200 response: description (in: body, type: string)'],'put /b/{}'=>['missing attribute from 200 response: description (in: body, type: string)']}}

You can also directly invoke the changes function:

diff=Swagger::Diff::Diff.new(<old>, <new>)diff.changes

#changes will return a hash containing the changed endpoints, request parameters, and response attributes; e.g.,

{new_endpoints: ['delete /pets/{}','get /pets/{}','post /pets'],new_request_params: {'get /pets'=>['new request param: tags (in: query, type: array)','new request param: limit (in: query, type: integer)']},new_response_attributes: {},removed_endpoints: [],removed_request_params: {},removed_response_attributes: {}}

Command-Line

It also includes a command-line version:

$ swagger-diff -i <old><new>

swagger-diff will print a list of any backwards-incompatibilities new has when compared to old.

For backwards-compatibility with previous versions of swagger-diff, the -i argument is optional:

$ swagger-diff <old><new>

The command-line version can also be used to generate a list of all changes (i.e., a changelog):

$ swagger-diff -c <old><new>

Gem Development

After checking out the repo, run bin/setup to install dependencies. Then, run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release to create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

See CONTRIBUTING.

License

Swagger::Diff is released under the BSD 3-Clause License.

OpenAPI (fka Swagger) Specification License

Swagger::Diff includes an unmodified copy of the OpenAPI Specification. The OpenAPI Specification is licensed under the Apache License, Version 2.0.

JSON Schema Specification License

Swagger::Diff includes an unmodified copy of the JSON Schema Specification, draft v4. The JSON Schema Specification is licensed under the Simplified BSD License.