Utility for comparing two Swagger specifications.
Utility for comparing two Swagger specifications.
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:
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.
Add this line to your application's Gemfile:
gem 'swagger-diff'And then execute:
$ bundleOr install it yourself as:
$ gem install swagger-diffOAI specifications can be any valid OAI file format, raw or parsed:
/path/to/specification.json) or remote (e.g.,
http://host.domain/specification.yml)JSON.parse)expect().to be_compatible_with()If new is incompatible with old, the spec will fail and print a list of
backwards-incompatibilities.
If you are not using RSpec, you can directly invoke the comparison function:
diff = Swagger::Diff::Diff.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(, )
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: {}
}It also includes a command-line version:
$ swagger-diff -i 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 The command-line version can also be used to generate a list of all changes (i.e., a changelog):
$ swagger-diff -c 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.
See CONTRIBUTING.
Swagger::Diff is released under the BSD 3-Clause License.
Swagger::Diff includes an unmodified copy of the OpenAPI Specification. The OpenAPI Specification is licensed under the Apache License, Version 2.0.
Swagger::Diff includes an unmodified copy of the JSON Schema Specification, draft v4. The JSON Schema Specification is licensed under the Simplified BSD License.
No open issues yet, or sync has not completed.