|
| 1 | +# Swagger::Diff |
| 2 | + |
| 3 | +[](https://travis-ci.org/civisanalytics/swagger-diff) |
| 4 | + |
| 5 | + |
| 6 | + |
| 7 | +> You can tell me by the way I walk - Genesis |
| 8 | +
|
| 9 | +Swagger::Diff is a utility for comparing two different |
| 10 | +[Swagger](http://swagger.io/) specifications. |
| 11 | +Its intended use is to determine whether a newer API specification is |
| 12 | +backwards-compatible with an older API specification. |
| 13 | +It provides both an [RSpec](http://rspec.info/) matcher and helper functions |
| 14 | +that can be used directly. |
| 15 | +Specifications are considered backwards compatible if: |
| 16 | + |
| 17 | +- all path and verb combinations in the old specification are present in the |
| 18 | + new one |
| 19 | +- no request parameters are required in the new specification that were not |
| 20 | + required in the old one |
| 21 | +- all request parameters in the old specification are present in the new one |
| 22 | +- all request parameters in the old specification have the same type in the |
| 23 | + new one |
| 24 | +- all response attributes in the old specification are present in the new one |
| 25 | +- all response attributes in the old specification have the same type in the new |
| 26 | + one |
| 27 | + |
| 28 | +## Installation |
| 29 | + |
| 30 | +Add this line to your application's Gemfile: |
| 31 | + |
| 32 | +```ruby |
| 33 | +gem 'swagger-diff' |
| 34 | +``` |
| 35 | + |
| 36 | +And then execute: |
| 37 | + |
| 38 | + $ bundle |
| 39 | + |
| 40 | +Or install it yourself as: |
| 41 | + |
| 42 | + $ gem install swagger-diff |
| 43 | + |
| 44 | +## Usage |
| 45 | + |
| 46 | +Swagger::Diff uses the [Swagger](https://github.com/swagger-rb/swagger-rb) gem |
| 47 | +to parse Swagger specifications. |
| 48 | +Specifications can be any |
| 49 | +[supported format](https://github.com/swagger-rb/swagger-rb/tree/v0.2.3#parsing): |
| 50 | + |
| 51 | +- the path to a file containing a Swagger specification. |
| 52 | + This may be local (*e.g.*, `/path/to/swagger.json`) or remote (*e.g.*, |
| 53 | + `http://host.domain/swagger.yml`) |
| 54 | +- a Hash containing a parsed Swagger specification (*e.g.*, the output of |
| 55 | + `JSON.parse`) |
| 56 | +- a string of JSON containing Swagger specification |
| 57 | +- a string of YAML containing Swagger specification |
| 58 | + |
| 59 | +### RSpec |
| 60 | + |
| 61 | +```ruby |
| 62 | +expect(<new>).to be_compatible_with(<old>) |
| 63 | +``` |
| 64 | + |
| 65 | +If `new` is incompatible with `old`, the spec will fail and print a list of |
| 66 | +backwards-incompatibilities. |
| 67 | + |
| 68 | +### Direct Invocation |
| 69 | + |
| 70 | +If you are not using RSpec, you can directly invoke the comparison function: |
| 71 | + |
| 72 | +```ruby |
| 73 | +diff = Swagger::Diff::Diff.new(<old>, <new>) |
| 74 | +diff.compatible? |
| 75 | +``` |
| 76 | + |
| 77 | +It will return `true` if `new` is compatible with `old`, `false` otherwise. |
| 78 | +`#incompatibilities` will return a hash containing the incompatible endpoints, |
| 79 | +request parameters, and response attributes; *e.g.*, |
| 80 | + |
| 81 | +```ruby |
| 82 | +{ endpoints: ['put /a/{}'], |
| 83 | + request_params: { |
| 84 | + 'get /a/' => ['missing request param: limit (type: integer)'], |
| 85 | + 'post /a/' => ['new required request param: extra'], |
| 86 | + 'put /b/{}' => ['new required request param: extra'] |
| 87 | + }, |
| 88 | + response_attributes: { |
| 89 | + 'post /a/' => ['missing attribute from 200 response: description (type: string)'], |
| 90 | + 'get /a/{}' => ['missing attribute from 200 response: description (type: string)'], |
| 91 | + 'put /b/{}' => ['missing attribute from 200 response: description (type: string)'] |
| 92 | + } |
| 93 | +} |
| 94 | +``` |
| 95 | + |
| 96 | +### Command-Line |
| 97 | + |
| 98 | +It also includes a command-line version: |
| 99 | + |
| 100 | +```bash |
| 101 | +$ swagger-diff <old> <new> |
| 102 | +``` |
| 103 | + |
| 104 | +`swagger-diff` will print a list of any backwards-incompatibilities `new` has |
| 105 | +when compared to `old`. |
| 106 | + |
| 107 | +## Gem Development |
| 108 | + |
| 109 | +After checking out the repo, run `bin/setup` to install dependencies. |
| 110 | +Then, run `bin/console` for an interactive prompt that will allow you to experiment. |
| 111 | + |
| 112 | +To install this gem onto your local machine, run `bundle exec rake install`. |
| 113 | +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](https://rubygems.org). |
| 114 | + |
| 115 | +## Contributing |
| 116 | + |
| 117 | +1. Fork it ( https://github.com/civisanalytics/swagger-diff/fork ) |
| 118 | +2. Create your feature branch (`git checkout -b my-new-feature`) |
| 119 | +3. Commit your changes (`git commit -am 'Add some feature'`) |
| 120 | +4. Push to the branch (`git push origin my-new-feature`) |
| 121 | +5. Create a new Pull Request |
| 122 | + |
| 123 | +## License |
| 124 | + |
| 125 | +Swagger::Diff is released under the [BSD 3-Clause License](LICENSE.txt). |
0 commit comments