swagger-diff 1.0.5 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4b908f910198d381cab6749fceb46dc189fcb824
-  data.tar.gz: f78caffe05399b68b448a021e7dd4b8c19ef1fba
+  metadata.gz: 7025ab8a26aa9eb452cbb399bf2fbde273f46299
+  data.tar.gz: 2a57c963078b714a2e1fa042ce12b2c3fbfa37a3
 SHA512:
-  metadata.gz: 7e534c39a09234677cf591f360d1f329a6f511cc16a052bd2ec49a474bcc87413cd78b4ce40b8e0b8a5408e6b78e7655b6f575c55d16047c3910ed382ab3dad0
-  data.tar.gz: d714909471d1c5d605d67c88f44fd07985d70abe94e1ba434b3a57522ab577f01e056fd91de566ff22e2c1c474cf44319576a02ef6b78b7e4ff4c871d1fc89a3
+  metadata.gz: 5963d3d5faf6c84097ffa29ab5cbe45a91b9b7dfa945571aa418ea6a1cb48c9c907a125f47df06c31f5f8b6bb4bdb0c0043a339d15fdb0ccebb6c4545e79b575
+  data.tar.gz: 5f3579dd89962e0ebb2e88440f8b195886a00002fc147b94e0369f81be4ec2a686dc008918e4a5b129374e089691ebbc3ecfdb57c60bc8359857d00b6da76127

data/.rubocop.yml

@@ -2,7 +2,7 @@ Metrics/AbcSize:
   Max: 30
 
 Metrics/ClassLength:
-  Max: 200
+  Max: 240
 
 Metrics/LineLength:
   Max: 120

data/.ruby-version

@@ -1 +1 @@
-2.2.3
+2.3.1

data/.travis.yml

@@ -1,5 +1,13 @@
 language: ruby
 cache: bundler
+rvm:
+  - 2.0
+  - 2.1.9
+  - 2.2.5
+  - 2.3.1
+before_install:
+  - gem update --system
+  - rvm @global do gem install bundler
 branches:
   only:
     - master

data/CHANGELOG.md

@@ -1,49 +1,88 @@
 # Change Log
 
-## 1.0.5 (2015-11-16)
+All notable changes to this project will be documented in this file.
+This project adheres to [Semantic Versioning](http://semver.org/).
 
-### Bugs Fixed
+## [Unreleased]
+
+## [1.1.0] - 2016-05-20
+
+### Added
+
+* Added a [Code of Conduct](CODE_OF_CONDUCT.md)
+* Added a matrix build of 2.0, 2.1, 2.2, and 2.3 to Travis
+* [#33](https://github.com/civisanalytics/swagger-diff/pull/33)
+  added a changelog feature
+* [#35](https://github.com/civisanalytics/swagger-diff/pull/35)
+  print a warning if an OAI specification is invalid
+
+### Changed
+
+* Bumped the Ruby version for development to 2.3.1
+* Bumped the RuboCop version for development to 0.40
+* Bumped the WebMock version for development to 2.0
+* Bumped the Rake version for development to 11.1
+
+### Fixed
+
+* [#27](https://github.com/civisanalytics/swagger-diff/pull/27)
+  made the Ruby 2.0+ dependency explicit
+* [#32](https://github.com/civisanalytics/swagger-diff/pull/32)
+  replaced the Swagger parser
+
+## [1.0.5] - 2015-11-16
+
+### Fixed
 
 * [#18](https://github.com/civisanalytics/swagger-diff/pull/18)
   parse non-ref parameter schemas (`allOf`, `properties`, and `items`)
 
-## 1.0.4 (2015-11-11)
+## [1.0.4] - 2015-11-11
 
-### Bugs Fixed
+### Fixed
 
 * [#14](https://github.com/civisanalytics/swagger-diff/pull/14)
   allow schema definitions without properties
 * [#15](https://github.com/civisanalytics/swagger-diff/pull/15)
   parse non-ref response schemas (`allOf`, `properties`, and `items`)
 
-## 1.0.3 (2015-11-04)
+## [1.0.3] - 2015-11-04
 
-### Changes
+### Added
 
 * Added a default Rake task to run Rubocop and RSpec
 * Added [CONTRIBUTING.md](CONTRIBUTING.md)
 
-### Bugs Fixed
+### Fixed
 
 * [#8](https://github.com/civisanalytics/swagger-diff/pull/8)
   fixed parsing of header and formData parameters
 * [#10](https://github.com/civisanalytics/swagger-diff/pull/10)
   detect if a parameter's location (*i.e.*, `in` value) changes
 
-## 1.0.2 (2015-10-08)
+## [1.0.2] - 2015-10-08
 
-### Bugs Fixed
+### Fixed
 
 * [#3](https://github.com/civisanalytics/swagger-diff/pull/3)
   treat required elements in new child parameters as backwards-compatible
 
-## 1.0.1 (2015-10-01)
+## [1.0.1] - 2015-10-01
 
-### Bugs Fixed
+### Fixed
 
 * [#1](https://github.com/civisanalytics/swagger-diff/pull/1)
   added missing rspec-expectations dependency
 
-## 1.0.0 (2015-10-01)
+## [1.0.0] - 2015-10-01 - [YANKED]
 
 * Initial Release
+
+[Unreleased]: https://github.com/civisanalytics/swagger-diff/compare/v1.1.0...HEAD
+[1.1.0]: https://github.com/civisanalytics/swagger-diff/compare/v1.0.5...v1.1.0
+[1.0.5]: https://github.com/civisanalytics/swagger-diff/compare/v1.0.4...v1.0.5
+[1.0.4]: https://github.com/civisanalytics/swagger-diff/compare/v1.0.3...v1.0.4
+[1.0.3]: https://github.com/civisanalytics/swagger-diff/compare/v1.0.2...v1.0.3
+[1.0.2]: https://github.com/civisanalytics/swagger-diff/compare/v1.0.1...v1.0.2
+[1.0.1]: https://github.com/civisanalytics/swagger-diff/compare/v1.0.0...v1.0.1
+[1.0.0]: https://github.com/civisanalytics/swagger-diff/commit/0f6390eedef2428e78bbd816cbb14f724543f59b

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,50 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, and in the interest of
+fostering an open and welcoming community, we pledge to respect all people who
+contribute through reporting issues, posting feature requests, updating
+documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free
+experience for everyone, regardless of level of experience, gender, gender
+identity and expression, sexual orientation, disability, personal appearance,
+body size, race, ethnicity, age, religion, or nationality.
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery
+* Personal attacks
+* Trolling or insulting/derogatory comments
+* Public or private harassment
+* Publishing other's private information, such as physical or electronic
+  addresses, without explicit permission
+* Other unethical or unprofessional conduct
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+By adopting this Code of Conduct, project maintainers commit themselves to
+fairly and consistently applying these principles to every aspect of managing
+this project. Project maintainers who do not follow or enforce the Code of
+Conduct may be permanently removed from the project team.
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting a project maintainer at opensource@civisanalytics.com.
+All complaints will be reviewed and investigated and will result in a response
+that is deemed necessary and appropriate to the circumstances. Maintainers are
+obligated to maintain confidentiality with regard to the reporter of an
+incident.
+
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 1.3.0, available at
+[http://contributor-covenant.org/version/1/3/0/][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/3/0/

data/CONTRIBUTING.md

@@ -1,6 +1,8 @@
 # Contributing to Swagger::Diff
 
-We welcome pull requests from everyone!
+We welcome bug reports and pull requests from everyone!
+This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
 
 ## Getting Started
 

data/README.md

@@ -9,7 +9,8 @@
 > You can tell me by the way I walk - Genesis
 
 Swagger::Diff is a utility for comparing two different
-[Swagger](http://swagger.io/) specifications.
+[Open API Initiative (OAI)](https://openapis.org/) specifications (fka
+[Swagger](http://swagger.io/) 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](http://rspec.info/) matcher and helper functions
@@ -27,6 +28,9 @@ Specifications are considered backwards compatible if:
 - 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](https://civisanalytics.com/blog/engineering/2015/10/02/using-swagger-to-detect-breaking-api-changes/).
 
 ## Installation
@@ -47,18 +51,15 @@ Or install it yourself as:
 
 ## Usage
 
-Swagger::Diff uses the [Swagger](https://github.com/swagger-rb/swagger-rb) gem
-to parse Swagger specifications.
-Specifications can be any
-[supported format](https://github.com/swagger-rb/swagger-rb/tree/v0.2.3#parsing):
+Swagger specifications can be any valid Swagger file format, raw or parsed:
 
-- the path to a file containing a Swagger specification.
+- the path to a file containing an OAI specification.
   This may be local (*e.g.*, `/path/to/swagger.json`) or remote (*e.g.*,
   `http://host.domain/swagger.yml`)
-- a Hash containing a parsed Swagger specification (*e.g.*, the output of
+- a Hash containing a parsed OAI specification (*e.g.*, the output of
   `JSON.parse`)
-- a string of JSON containing a Swagger specification
-- a string of YAML containing a Swagger specification
+- a string of JSON containing an OAI specification
+- a string of YAML containing an OAI specification
 
 ### RSpec
 
@@ -97,17 +98,53 @@ request parameters, and response attributes; *e.g.*,
 }
 ```
 
+You can also directly invoke the changes function:
+
+```ruby
+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.*,
+
+```ruby
+{ 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:
 
 ```bash
-$ swagger-diff <old> <new>
+$ 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:
+
+```bash
+$ swagger-diff <old> <new>
+```
+
+The command-line version can also be used to generate a list of all changes
+(*i.e.*, a changelog):
+
+```bash
+$ swagger-diff -c <old> <new>
+```
+
 ## Gem Development
 
 After checking out the repo, run `bin/setup` to install dependencies.
@@ -122,4 +159,18 @@ See [CONTRIBUTING](CONTRIBUTING.md).
 
 ## License
 
-Swagger::Diff is released under the [BSD 3-Clause License](LICENSE.txt).
+Swagger::Diff is released under the [BSD 3-Clause License](LICENSE.md).
+
+## OpenAPI (fka Swagger) Specification License
+
+Swagger::Diff includes an
+[unmodified copy of the OpenAPI Specification](schema/oai/schema.json).
+The OpenAPI Specification is licensed under the
+[Apache License, Version 2.0](schema/oai/LICENSE.md).
+
+## JSON Schema Specification License
+
+Swagger::Diff includes an
+[unmodified copy of the JSON Schema Specification, draft v4](schema/json/schema.json).
+The JSON Schema Specification is licensed under the
+[Simplified BSD License](schema/json/LICENSE.md).

data/exe/swagger-diff

@@ -1,17 +1,49 @@
 #!/usr/bin/env ruby
 
+require 'optparse'
 require 'swagger/diff'
 
+options = {}
+OptionParser.new do |opts|
+  opts.banner = 'Usage: swagger-diff [options] <old> <new>'
+
+  opts.on('-c', '--changes',
+          'Generate a list of changes between <new>',
+          'and <old>') do |c|
+    options[:changes] = c
+  end
+
+  opts.on('-i', '--incompatibilities',
+          'Checks <new> for backwards-compatibility',
+          'with <old>. If <new> is incompatible, a',
+          'list of incompatibilities will be printed.') do |i|
+    options[:incompatibilities] = i
+  end
+
+  opts.on_tail('-h', '--help', 'This message') do
+    puts opts
+    exit
+  end
+
+  opts.on_tail('-v', '--version', 'Display the version') do
+    puts Swagger::Diff::VERSION
+    exit
+  end
+
+  options[:help] = opts
+end.parse!
+
 if ARGV.length == 2
   diff = Swagger::Diff::Diff.new(ARGV[0], ARGV[1])
 
-  unless diff.compatible?
-    puts diff.incompatibilities_message
-    exit 1
+  if options[:changes]
+    puts diff.changes_message
+  else
+    unless diff.compatible?
+      puts diff.incompatibilities_message
+      exit 1
+    end
   end
 else
-  puts 'Usage: swagger-diff <old> <new>
-
-Checks <new> for backwards-compatibility with <old>. If <new> is incompatible,
-a list of incompatibilities will be printed.'
+  puts options[:help]
 end

data/lib/swagger/diff.rb

@@ -1,8 +1,10 @@
-require 'forwardable' # Needed to require swagger-core.
-require 'swagger'
+require 'json'
+require 'open-uri'
+require 'set'
+require 'yaml'
+require 'json-schema'
 require 'rspec/expectations'
 require 'swagger/diff/diff'
-require 'swagger/diff/patch'
 require 'swagger/diff/rspec_matchers'
 require 'swagger/diff/specification'
 require 'swagger/diff/version'

data/lib/swagger/diff/diff.rb

@@ -6,37 +6,69 @@ module Swagger
         @old_specification = Swagger::Diff::Specification.new(old)
       end
 
+      def changes
+        @changes ||= {
+          new_endpoints: new_endpoints.to_a.sort,
+          removed_endpoints: missing_endpoints.to_a.sort,
+          new_request_params: new_or_changed_request_params,
+          removed_request_params: incompatible_request_params,
+          new_response_attributes: new_or_changed_response_attributes,
+          removed_response_attributes: incompatible_response_attributes
+        }
+      end
+
+      def changes_message
+        changed_endpoints_message + changed_params_message + changed_attrs_message
+      end
+
       def compatible?
         endpoints_compatible? && requests_compatible? && responses_compatible?
       end
 
       def incompatibilities
-        { endpoints: missing_endpoints.to_a.sort,
+        @incompatibilities ||= {
+          endpoints: missing_endpoints.to_a.sort,
           request_params: incompatible_request_params,
-          response_attributes: incompatible_response_attributes }
+          response_attributes: incompatible_response_attributes
+        }
       end
 
       def incompatibilities_message
         msg = ''
-        if incompatibilities[:endpoints]
-          msg += incompatibilities_message_endpoints(incompatibilities[:endpoints])
-        end
-        if incompatibilities[:request_params]
-          msg += incompatibilities_message_params(incompatibilities[:request_params])
-        end
-        if incompatibilities[:response_attributes]
-          msg += incompatibilities_message_attributes(incompatibilities[:response_attributes])
-        end
+        msg += endpoints_message('missing', incompatibilities[:endpoints])
+        msg += params_message('incompatible', incompatibilities[:request_params])
+        msg += attributes_message('incompatible', incompatibilities[:response_attributes])
         msg
       end
 
       private
 
-      def incompatibilities_message_endpoints(endpoints)
+      def changed_endpoints_message
+        msg = ''
+        msg += endpoints_message('new', changes[:new_endpoints])
+        msg += endpoints_message('removed', changes[:removed_endpoints])
+        msg
+      end
+
+      def changed_params_message
+        msg = ''
+        msg += params_message('new', changes[:new_request_params])
+        msg += params_message('removed', changes[:removed_request_params])
+        msg
+      end
+
+      def changed_attrs_message
+        msg = ''
+        msg += attributes_message('new', changes[:new_response_attributes])
+        msg += attributes_message('removed', changes[:removed_response_attributes])
+        msg
+      end
+
+      def endpoints_message(type, endpoints)
         if endpoints.empty?
           ''
         else
-          msg = "- missing endpoints\n"
+          msg = "- #{type} endpoints\n"
           endpoints.each do |endpoint|
             msg += "  - #{endpoint}\n"
           end
@@ -44,11 +76,11 @@ module Swagger
         end
       end
 
-      def incompatibilities_message_inner(typestr, collection)
+      def inner_message(nature, type, collection)
         if collection.nil? || collection.empty?
           ''
         else
-          msg = "- incompatible #{typestr}\n"
+          msg = "- #{nature} #{type}\n"
           collection.sort.each do |endpoint, attributes|
             msg += "  - #{endpoint}\n"
             attributes.each do |attribute|
@@ -59,27 +91,45 @@ module Swagger
         end
       end
 
-      def incompatibilities_message_params(params)
-        incompatibilities_message_inner('request params', params)
+      def params_message(type, params)
+        inner_message(type, 'request params', params)
       end
 
-      def incompatibilities_message_attributes(attributes)
-        incompatibilities_message_inner('response attributes', attributes)
+      def attributes_message(type, attributes)
+        inner_message(type, 'response attributes', attributes)
       end
 
       def missing_endpoints
         @old_specification.endpoints - @new_specification.endpoints
       end
 
-      def incompatible_request_params
+      def new_endpoints
+        @new_specification.endpoints - @old_specification.endpoints
+      end
+
+      def change_hash(enumerator)
         ret = {}
-        incompatible_request_params_enumerator.each do |key, val|
+        enumerator.each do |key, val|
           ret[key] ||= []
           ret[key] << val
         end
         ret
       end
 
+      def incompatible_request_params
+        change_hash(incompatible_request_params_enumerator)
+      end
+
+      def new_or_changed_request_params
+        enumerator = changed_request_params_enumerator(
+          @new_specification,
+          @old_specification,
+          '%{req} is no longer required',
+          'new request param: %{req}'
+        )
+        change_hash(enumerator)
+      end
+
       def new_child?(req, old)
         idx = req.rindex('/')
         return false unless idx
@@ -87,49 +137,72 @@ module Swagger
         !old.any? { |param| param.start_with?(key) }
       end
 
-      def incompatible_request_params_enumerator
+      def changed_request_params_enumerator(from, to, req_msg, missing_msg)
         Enumerator.new do |yielder|
-          @old_specification.request_params.each do |key, old_params|
-            new_params = @new_specification.request_params[key]
+          from.request_params.each do |key, old_params|
+            new_params = to.request_params[key]
             next if new_params.nil?
             (new_params[:required] - old_params[:required]).each do |req|
               next if new_child?(req, old_params[:all])
-              yielder << [key, "new required request param: #{req}"]
+              yielder << [key, req_msg % { req: req }]
             end
             (old_params[:all] - new_params[:all]).each do |req|
-              yielder << [key, "missing request param: #{req}"]
+              yielder << [key, missing_msg % { req: req }]
             end
           end
         end.lazy
       end
 
+      def incompatible_request_params_enumerator
+        changed_request_params_enumerator(
+          @old_specification,
+          @new_specification,
+          'new required request param: %{req}',
+          'missing request param: %{req}'
+        )
+      end
+
       def incompatible_response_attributes
-        ret = {}
-        incompatible_response_attributes_enumerator.each do |key, val|
-          ret[key] ||= []
-          ret[key] << val
-        end
-        ret
+        change_hash(incompatible_response_attributes_enumerator)
       end
 
-      def incompatible_response_attributes_enumerator
+      def new_or_changed_response_attributes
+        enumerator = changed_response_attributes_enumerator(
+          @new_specification,
+          @old_specification,
+          'new attribute for %{code} response: %{resp}',
+          'new %{code} response'
+        )
+        change_hash(enumerator)
+      end
+
+      def changed_response_attributes_enumerator(from, to, attr_msg, code_msg)
         Enumerator.new do |yielder|
-          @old_specification.response_attributes.each do |key, old_attributes|
-            new_attributes = @new_specification.response_attributes[key]
+          from.response_attributes.each do |key, old_attributes|
+            new_attributes = to.response_attributes[key]
             next if new_attributes.nil?
             old_attributes.keys.each do |code|
               if new_attributes.key?(code)
                 (old_attributes[code] - new_attributes[code]).each do |resp|
-                  yielder << [key, "missing attribute from #{code} response: #{resp}"]
+                  yielder << [key, attr_msg % { code: code, resp: resp }]
                 end
               else
-                yielder << [key, "missing #{code} response"]
+                yielder << [key, code_msg % { code: code }]
               end
             end
           end
         end.lazy
       end
 
+      def incompatible_response_attributes_enumerator
+        changed_response_attributes_enumerator(
+          @old_specification,
+          @new_specification,
+          'missing attribute from %{code} response: %{resp}',
+          'missing %{code} response'
+        )
+      end
+
       def endpoints_compatible?
         missing_endpoints.empty?
       end