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>).to be_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.