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.