apipie-rails 0.3.6 → 0.5.17

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 5d6fc12663b63923153a8f238fac0c7556257aeb
-  data.tar.gz: 2271e183d1319d0d42df3d909285d7ded70970aa
+SHA256:
+  metadata.gz: 855ada05457368ea7521d46865242c73a15c33a33546d7b0dac1d2b90d779c70
+  data.tar.gz: 0cc30d4f4a38a476cab6ed92b6a4a00c45bd2036c8b35fb8373fbb215fb2ea80
 SHA512:
-  metadata.gz: 7864fe236a067ce5a0a3068a51d01a53b641ade349f6f5dc8b2d9ebc242e8c078de8601d82e62c4560770e9c537bfe98771e1f24c4b693fb31cb5fc32148d91d
-  data.tar.gz: fb902c9fc943fb6f3067576af5db940b015009810d908ccb02d684e9364e9cb293dc257d73848c7fee42cf356ad9756189734e0e5811e8f3ee07083535f483c2
+  metadata.gz: 9b0ba79aee65ed21249fa35336166783697719fabc74831816513ea1d0b91162bde342b51fad08121ea38c27f5015bbf196ac524049dcbbc8635dd0a57f13cff
+  data.tar.gz: 0f9f593ee579dba0baf16175e8c9d916dd370eba6a5c37cee4df2a92dea1efe0ea936b2444597274dd327244063000bb3a9cff454413956cd98bd27c5652afc6

data/.travis.yml

@@ -1,12 +1,28 @@
 language: ruby
 sudo: false
+before_install: >-
+  if ruby -v | grep 'ruby 2.2'; then
+    gem install bundler -v '~> 1.17'
+  fi
 rvm:
-  - 1.9.3
-  - 2.0.0
-  - 2.1.7
-  - 2.2.3
+  - 2.2.10
+  - 2.3.8
+  - 2.4.5
+  - 2.5.3
+  - 2.6.0
 gemfile:
-  - Gemfile.rails32
-  - Gemfile.rails40
-  - Gemfile.rails41
   - Gemfile.rails42
+  - Gemfile.rails51 # Min ruby 2.2.2
+  - Gemfile.rails60 # Min ruby 2.5.0
+matrix:
+  exclude:
+    - rvm: 2.5.3
+      gemfile: Gemfile.rails42
+    - rvm: 2.6.0
+      gemfile: Gemfile.rails42
+    - rvm: 2.2.10
+      gemfile: Gemfile.rails60
+    - rvm: 2.3.8
+      gemfile: Gemfile.rails60
+    - rvm: 2.4.5
+      gemfile: Gemfile.rails60

data/CHANGELOG.md

@@ -1,7 +1,152 @@
-===========
  Changelog
 ===========
 
+[v0.5.17](https://github.com/Apipie/apipie-rails/tree/v0.5.17) (2020-01-20)
+--------
+
+[Full Changelog](https://github.com/Apipie/apipie-rails/compare/v0.5.16...v0.5.17)
+
+- Allows update metadata for methods [\#667](https://github.com/Apipie/apipie-rails/pull/667) ([speckins](https://github.com/speckins))
+
+[v0.5.16](https://github.com/Apipie/apipie-rails/tree/v0.5.16) (2019-05-22)
+--------
+
+[Full Changelog](https://github.com/Apipie/apipie-rails/compare/v0.5.15...v0.5.16)
+
+- Load file directly instead of using Rails constant [\#665](https://github.com/Apipie/apipie-rails/pull/665) ([speckins](https://github.com/speckins))
+
+[v0.5.15](https://github.com/Apipie/apipie-rails/tree/v0.5.15) (2019-01-03)
+--------
+[Full Changelog](https://github.com/Apipie/apipie-rails/compare/v0.5.14...v0.5.15)
+
+
+- Fix authorization of resources [\#655](https://github.com/Apipie/apipie-rails/pull/655) ([NielsKSchjoedt](https://github.com/NielsKSchjoedt))
+- Use configured value when swagger\_content\_type\_input argument is not passed [\#648](https://github.com/Apipie/apipie-rails/pull/648) ([nullnull](https://github.com/nullnull))
+- Fix "ArgumentError: string contains null byte" on malformed stings [\#477](https://github.com/Apipie/apipie-rails/pull/477) ([avokhmin](https://github.com/avokhmin))
+
+v0.5.14
+-------
+- HTML escape validator values [\#645](https://github.com/Apipie/apipie-rails/pull/645) ([ekohl](https://github.com/ekohl))
+- Support for adding new params via `update\_api` [\#642](https://github.com/Apipie/apipie-rails/pull/642) ([iNecas](https://github.com/iNecas))
+- Allow the "null" JSON string to be used as a parameter in Apipie spec examples \(`show\_in\_doc`\) [\#641](https://github.com/Apipie/apipie-rails/pull/641) ([enrique-guillen](https://github.com/enrique-guillen))
+- Fix examples recording for specific cases  [\#640](https://github.com/Apipie/apipie-rails/pull/640) ([Marri](https://github.com/Marri))
+- Add description section to response [\#639](https://github.com/Apipie/apipie-rails/pull/639) ([X1ting](https://github.com/X1ting))
+
+
+v0.5.13
+-------
+-  Fix swagger generation if a controller's parent doesn't define a resource_description [\#637](https://github.com/Apipie/apipie-rails/pull/637) ([enrique-guillen](https://github.com/enrique-guillen))
+
+v0.5.12
+-------
+- Fix returns displaying [\#635](https://github.com/Apipie/apipie-rails/pull/635) ([X1ting](https://github.com/X1ting))
+
+v0.5.11
+-------
+
+- Adds swagger tags in swagger output [\#634](https://github.com/Apipie/apipie-rails/pull/634) ([enrique-guillen](https://github.com/enrique-guillen))
+- Generate swagger with headers [\#630](https://github.com/Apipie/apipie-rails/pull/630) ([Uysim](https://github.com/Uysim))
+- Fix examples not being generated for Rails < 5.0.0 [\#633](https://github.com/Apipie/apipie-rails/pull/633) ([RomanKapitonov](https://github.com/RomanKapitonov))
+
+v0.5.10
+------
+
+- Support response validation [\#626](https://github.com/Apipie/apipie-rails/pull/626) ([COzero](https://github.com/COzero))
+
+v0.5.9
+------
+
+- Support response validation [\#619](https://github.com/Apipie/apipie-rails/pull/619) ([abenari](https://github.com/abenari))
+- Expect :number to have type 'numeric' [\#614](https://github.com/Apipie/apipie-rails/pull/614) ([akofink](https://github.com/akofink))
+- New validator - DecimalValidator [\#431](https://github.com/Apipie/apipie-rails/pull/431) ([kiddrew](https://github.com/kiddrew))
+
+
+v0.5.8
+------
+
+- Swagger json includes apipie's description as swagger's description [\#615](https://github.com/Apipie/apipie-rails/pull/615) ([gogotanaka](https://github.com/gogotanaka))
+- Fix api! issue by using underscore when appending `controller` to the default controller string [\#613](https://github.com/Apipie/apipie-rails/pull/613) ([kevinmarx](https://github.com/kevinmarx))
+- Possibility to compress examples [\#600](https://github.com/Apipie/apipie-rails/pull/600) ([Haniyya](https://github.com/Haniyya))
+- Possibility to describe responses [\#588](https://github.com/Apipie/apipie-rails/pull/588) ([elasti-ron](https://github.com/elasti-ron))
+
+v0.5.7
+------
+
+- Fix example recording with Rails 5 [\#607](https://github.com/Apipie/apipie-rails/pull/607) ([adamruzicka](https://github.com/adamruzicka))
+- Use SHA1 instead of MD5 to enable using APIPIE at FIPS-enables systems [\#605](https://github.com/Apipie/apipie-rails/pull/605) ([iNecas](https://github.com/iNecas))
+- Replaced String\#constantize with String\#safe\_constantize so apipie won't break on a missing constant [\#575](https://github.com/Apipie/apipie-rails/pull/575) ([Haniyya](https://github.com/Haniyya))
+- Added Swagger generation [\#569](https://github.com/Apipie/apipie-rails/pull/569) ([elasti-ron](https://github.com/elasti-ron))
+
+v0.5.6
+------
+
+- Prevent missing translation span in title [\#571](https://github.com/Apipie/apipie-rails/pull/571) ([mbacovsky](https://github.com/mbacovsky))
+- Clean up old generator code for CLI [\#572](https://github.com/Apipie/apipie-rails/pull/572) ([voxik](https://github.com/voxik))
+- Added french locale [\#568](https://github.com/Apipie/apipie-rails/pull/568) ([giglemad](https://github.com/giglemad))
+
+v0.5.5
+------
+
+- prevent lang in url when config.translate is false [\#562](https://github.com/Apipie/apipie-rails/pull/562) ([markmoser](https://github.com/markmoser))
+- Allow for resource-level deprecations [\#567](https://github.com/Apipie/apipie-rails/pull/567) ([cross-p6](https://github.com/cross-p6))
+
+v0.5.4
+------
+
+- Constantize controller class before calling superclass [\#558](https://github.com/Apipie/apipie-rails/pull/558) ([ydkn](https://github.com/ydkn))
+
+v0.5.3
+------
+
+- Fix reloading when extending the apidoc from concern [\#557](https://github.com/Apipie/apipie-rails/pull/557) ([iNecas](https://github.com/iNecas))
+- Fix example recording when using send\_file [\#504](https://github.com/Apipie/apipie-rails/pull/504) ([tdeo](https://github.com/tdeo))
+
+v0.5.2
+------
+
+- A way to extend an exiting API via concern [\#554](https://github.com/Apipie/apipie-rails/pull/554) ([iNecas](https://github.com/iNecas))
+- Fallback to apipie views when application override isn't present [\#552](https://github.com/Apipie/apipie-rails/pull/552) ([tstrachota](https://github.com/tstrachota))
+- Updated setting default locale for api documentation [\#543](https://github.com/Apipie/apipie-rails/pull/543) ([DmitryKK](https://github.com/DmitryKK))
+
+v0.5.1
+------
+
+- Use AD::Reloader on Rails 4, app.reloader only on Rails 5+ [\#541](https://github.com/Apipie/apipie-rails/pull/541) ([domcleal](https://github.com/domcleal))
+- Recognize Rack Symbols as Status Codes [\#468](https://github.com/Apipie/apipie-rails/pull/468)([alex-tan](https://github.com/alex-tan))
+
+v0.5.0
+------
+
+- Fix Rails 5.1 deprecations [\#530](https://github.com/Apipie/apipie-rails/pull/530) ([@Onumis](https://github.com/Onumis) [@sedx](https://github.com/sedx))
+  - **This release is no longer compatible with Ruby 1.9.x**
+- Do not mutate strings passed as config options, fixes \#461 [\#537](https://github.com/Apipie/apipie-rails/pull/537) ([samphilipd](https://github.com/samphilipd))
+- Added recursion for documentation, fixed bug in examples with paperclip [\#531](https://github.com/Apipie/apipie-rails/pull/531) ([blddmnd](https://github.com/blddmnd))
+- Added locales/ja.yml for Japanese [\#529](https://github.com/Apipie/apipie-rails/pull/529) ([kikuchi0808](https://github.com/kikuchi0808))
+
+
+v0.4.0
+------
+
+- Rails 5 compatibility [\#527](https://github.com/Apipie/apipie-rails/pull/527) ([iNecas](https://github.com/iNecas)) [\#420](https://github.com/Apipie/apipie-rails/pull/420) ([buren](https://github.com/buren)) [\#473](https://github.com/Apipie/apipie-rails/pull/473)([domcleal](https://github.com/domcleal))
+  - **This release is no longer compatible with Rails 3.x**
+- Include delete request parmeters in generated documentation [\#524](https://github.com/Apipie/apipie-rails/pull/524) ([johnnaegle](https://github.com/johnnaegle))
+- Allow a blank, not just nil, base\_url. [\#521](https://github.com/Apipie/apipie-rails/pull/521) ([johnnaegle](https://github.com/johnnaegle))
+- Adds allow\_blank option [\#508](https://github.com/Apipie/apipie-rails/pull/508) ([MrLeebo](https://github.com/MrLeebo))
+- Boolean Validator uses \<code\> instead of ' [\#502](https://github.com/Apipie/apipie-rails/pull/502) ([berfarah](https://github.com/berfarah))
+- Fix type validator message [\#501](https://github.com/Apipie/apipie-rails/pull/501) ([cindygu-itglue](https://github.com/cindygu-itglue))
+- Add IT locale [\#496](https://github.com/Apipie/apipie-rails/pull/496) ([alepore](https://github.com/alepore))
+- Fix small typo on dsl\_definition data init [\#494](https://github.com/Apipie/apipie-rails/pull/494) ([begault](https://github.com/begault))
+- Localize app info message [\#491](https://github.com/Apipie/apipie-rails/pull/491) ([belousovAV](https://github.com/belousovAV))
+- Fix travis build [\#489](https://github.com/Apipie/apipie-rails/pull/489) ([mtparet](https://github.com/mtparet))
+- Handle blank data when parsing a example's response [\#453](https://github.com/Apipie/apipie-rails/pull/453) ([stbenjam](https://github.com/stbenjam))
+- Allow layouts to be overridable. Fixes a regression introduced in \#425. [\#447](https://github.com/Apipie/apipie-rails/pull/447) ([nilsojes](https://github.com/nilsojes))
+
+v0.3.7
+------
+
+- Handle blank data when parsing a example's response [\#453](https://github.com/Apipie/apipie-rails/pull/453) ([stbenjam](https://github.com/stbenjam))
+- Allow layouts to be overridable. Fixes a regression introduced in \#425. [\#447](https://github.com/Apipie/apipie-rails/pull/447) ([nilseriksson](https://github.com/nilseriksson))
+
 v0.3.6
 ------
 
@@ -70,7 +215,7 @@ v0.3.2
 v0.3.1
 ------
 
-* Support for ``api!`` keyword in concerns 
+* Support for ``api!`` keyword in concerns
   [#322](https://github.com/Apipie/apipie-rails/pull/322) [@iNecas][]
 * More explicit ordering of the static dispatcher middleware
   [#315](https://github.com/Apipie/apipie-rails/pull/315) [@iNecas][]

data/Gemfile

@@ -0,0 +1 @@
+./Gemfile.rails50

data/Gemfile.rails41

@@ -3,3 +3,5 @@ source "https://rubygems.org"
 gemspec
 
 gem 'rails', '~> 4.1.0'
+gem 'mime-types', '~> 2.99.3'
+gem 'test_engine', path: 'spec/dummy/components/test_engine', group: :test

data/Gemfile.rails42

@@ -2,4 +2,13 @@ source "https://rubygems.org"
 
 gemspec
 
-gem 'rails', '~> 4.2.5.1'
+gem 'rails', '~> 4.2.5'
+gem 'mime-types', '~> 2.99.3'
+gem 'sqlite3', '~> 1.3.6'
+
+if Gem::Version.new(RUBY_VERSION) < Gem::Version.new('2.1.0')
+  gem 'nokogiri', '~> 1.6.8'
+  gem 'rdoc', '~> 4.2.2'
+end
+
+gem 'test_engine', path: 'spec/dummy/components/test_engine', group: :test

data/Gemfile.rails50

@@ -0,0 +1,9 @@
+source "https://rubygems.org"
+
+gemspec
+
+gem 'rails', '~> 5.0.0'
+gem 'mime-types', '~> 2.99.3'
+gem 'rails-controller-testing'
+
+gem 'test_engine', path: 'spec/dummy/components/test_engine', group: :test

data/Gemfile.rails51

@@ -0,0 +1,9 @@
+source "https://rubygems.org"
+
+gemspec
+
+gem 'rails', '~> 5.1.0.rc1'
+gem 'mime-types', '~> 2.99.3'
+gem 'rails-controller-testing'
+
+gem 'test_engine', path: 'spec/dummy/components/test_engine', group: :test

data/Gemfile.rails60

@@ -0,0 +1,14 @@
+source "https://rubygems.org"
+
+gemspec
+
+gem 'rails', '~> 6.0.0.rc1'
+gem 'mime-types', '~> 2.99.3'
+gem 'rails-controller-testing'
+gem 'rspec-rails', git: 'https://github.com/rspec/rspec-rails', branch: '4-0-dev'
+gem 'rspec-core', git: 'https://github.com/rspec/rspec-core'
+gem 'rspec-mocks', git: 'https://github.com/rspec/rspec-mocks'
+gem 'rspec-support', git: 'https://github.com/rspec/rspec-support'
+gem 'rspec-expectations', git: 'https://github.com/rspec/rspec-expectations'
+
+gem 'test_engine', path: 'spec/dummy/components/test_engine', group: :test

data/PROPOSAL_FOR_RESPONSE_DESCRIPTIONS.md

@@ -0,0 +1,244 @@
+# Proposal for supporting response descriptions in Apipie
+
+## Rationale
+
+Swagger allows API authors to describe the structure of objects returned by REST API calls.
+Client authors and code generators can use such descriptions for various purposes, such as verification, 
+autocompletion, and so forth.
+
+The current Apipie DSL allows API authors to indicate returned error codes (using the `error` keyword), 
+but does not support descriptions of returned data objects. As such, swagger files
+generated from the DSL do not include those, and are somewhat limited in their value.
+
+This document proposes a minimalistic approach to extending the Apipie DSL to allow description of response
+objects, and including those descriptions in generated swagger files. 
+
+## Design Objectives
+
+* Full backward compatibility with the existing DSL
+* Minimal implementation effort
+* Enough expressiveness to support common use cases
+* Optional integration of the DSL with advanced JSON generators (such as Grape-Entity)   
+* Allowing developers to easily verify that actual responses match the response declarations   
+
+## Approach
+
+#### Add a `returns` keyword to the DSL, based on the existing `error` keyword
+
+Currently, returned error codes are indicated using the `error` keyword, for example:
+```ruby
+api :GET, "/users/:id", "Show user profile"
+error :code => 401, :desc => "Unauthorized"
+```
+
+The proposed approach is to add a `returns` keyword, that has the following syntax:
+```ruby
+returns <type-identifier> [, :code => <number>] [, :desc => <response-description>]
+```
+
+For example:
+```ruby
+api :GET, "/users/:id", "Show user profile"
+error :code => 401, :desc => "Unauthorized"
+returns :SomeTypeIdentifier  # :code is not specified, so it is assumed to be 200
+```
+
+
+#### Leverage `param_group` for response object description
+
+Apipie currently has a mechanism for describing complex objects using the `param_group` keyword.
+It seems reasonable to leverage this mechanism as the basis of the response object description mechanism,
+so that the `<type-identifier>` in the `returns` keyword will be the name of a param_group.
+
+For example:
+```ruby
+  def_param_group :user do
+    param :user, Hash, :desc => "User info", :required => true, :action_aware => true do
+      param_group :credentials
+      param :membership, ["standard","premium"], :desc => "User membership", :allow_nil => false
+    end
+  end
+
+  api :GET, "/users/:id", "Get user record"
+  returns :user, "the requested record"
+  error :code => 404, :desc => "no user with the specified id"
+```
+
+Implementation of this DSL extension would involve - as part of the implementation of the `returns` keyword - 
+the generation of a Apipie::ParamDescription object that has a Hash validator pointing to the param_group block.
+
+#### Extend action-aware functionality to include 'response-only' parameters
+
+In CRUD operations, it is common for `param_group` input definitions to be very similar to the 
+output of the API, with the exception of a very small number of fields (such as the `:id` field
+which usually appears in the response, but is not described in the `param_group` because it is passed as a 
+path parameter).
+
+To allow reuse of the `param_group`, it would be useful to its definition to describe parameters that are not passed 
+in the request but are returned in the response.  This would be implementing by extending the DSL to 
+support a `:only_in => :response` option on `param` definitions.  Similarly, params could be defined to be 
+`:only_in => :request` to indicate that they will not be included in the response.    
+
+For example:
+```ruby
+  # in the following group, the :id param is ignored in requests, but included in responses
+  def_param_group :user do
+    param :user, Hash, :desc => "User info", :required => true, :action_aware => true do
+      param :id, Integer, :only_in => :response
+      param :requested_id, Integer, :only_in => :request
+      param_group :credentials
+      param :membership, ["standard","premium"], :desc => "User membership", :allow_nil => false
+    end
+  end
+
+  api :GET, "/users/:id", "Get user record"
+  returns :user, :desc => "the requested record"  # includes the :id field, because this is a response
+  error :code => 404, :desc => "no user with the specified id"
+```
+
+
+#### Support `:array_of => <param_group-name>` in the `returns` keyword 
+
+Very often, a REST API call returns an array of some previously-defined object 
+(the most common example an `index` operation that returns an array of the same entity returned by a `show` request), 
+and it would be tedious to have to define a separate `param_group` for each one.
+
+For added convenience, the `returns` keyword will also support an `:array_of =>` construct
+to specify that an API call returns an array of some object type.
+
+For example:
+```ruby
+  api :GET, "/users", "Get all user records"
+  returns :array_of => :user, :desc => "the requested user records"
+
+  api :GET, "/user/:id", "Get a single user record"
+  returns :user, :desc => "the requested user record"
+```
+
+#### Integration with advanced JSON generators using an [adapter](https://en.wikipedia.org/wiki/Adapter_pattern) to `param_group`
+
+While it makes sense for the sake of simplicity to leverage the `param_group` construct to describe 
+returned objects, it is likely that many developers will prefer to unify the 
+description of the response with the actual generation of the JSON.
+
+Some JSON-generation libraries, such as [Grape-Entity](https://github.com/ruby-grape/grape-entity),
+provide a declarative interface for describing an object model, allowing both runtime
+generation of the response, as well as the ability to traverse the description to auto-generate
+documentation.
+
+Such libraries could be integrated with Apipie using adapters that wrap the library-specific
+object description and expose an API that includes a `params_ordered` method that behaves in a 
+similar manner to [`Apipie::HashValidator.params_ordered`](https://github.com/Apipie/apipie-rails/blob/cfb42198bc39b5b30d953ba5a8b523bafdb4f897/lib/apipie/validator.rb#L315).
+Such an adapter would make it possible to pass an externally-defined entity to the `returns` keyword
+as if it were a `param_group`.
+
+Such adapters can be created easily by having a class respond to `#describe_own_properties` 
+with an array of property description objects.  When such a class is specified as the 
+parameter to a `returns` declaration, Apipie would query the class for its properties
+by calling `<Class>#describe_own_properties`. 
+
+For example:
+```ruby
+# here is a class that can describe itself to Apipie
+class Animal
+  def self.describe_own_properties
+    [
+        Apipie::prop(:id, Integer, {:description => 'Name of pet', :required => false}),
+        Apipie::prop(:animal_type, 'string', {:description => 'Type of pet', :values => ["dog", "cat", "iguana", "kangaroo"]}),
+        Apipie::additional_properties(false)
+    ]
+  end
+  
+  attr_accessor :id
+  attr_accessor :animal_type  
+end
+
+# Here is an API defined as returning Animal objects.
+# Apipie creates an internal adapter by querying Animal#describe_own_properties
+api :GET, "/animals", "Get all records"
+returns :array_of => Animal, :desc => "the requested records"
+```
+
+The `#describe_own_properties` mechanism can also be used with reflection so that a
+class would query its own properties and populate the response to `#describe_own_properties`
+automatically.  See [this gist](https://gist.github.com/elasti-ron/ac145b2c85547487ca33e5216a69f527)  
+for an example of how Grape::Entity classes can automatically describe itself to Apipie
+
+#### Response validation
+
+The swagger definitions created by Apipie can be used to auto-generate clients that access the
+described APIs.  Those clients will break if the responses returned from the API do not match
+the declarations.  As such, it is very important to include unit tests that validate the actual
+responses against the swagger definitions.
+
+The ~~proposed~~ implemented mechanism provides two ways to include such validations in RSpec unit tests:
+manual (using an RSpec matcher) and automated (by injecting a test into the http operations 'get', 'post', 
+raising an error if there is no match).
+
+Example of the manual mechanism:
+
+```ruby
+require 'apipie/rspec/response_validation_helper'
+
+RSpec.describe MyController, :type => :controller, :show_in_doc => true do
+
+describe "GET stuff with response validation" do
+  render_views   # this makes sure the 'get' operation will actually
+                 # return the rendered view even though this is a Controller spec
+
+  it "does something" do
+    response = get :index, {format: :json}
+
+    # the following expectation will fail if the returned object
+    # does not match the 'returns' declaration in the Controller,
+    # or if there is no 'returns' declaration for the returned
+    # HTTP status code
+    expect(response).to match_declared_responses
+  end
+end
+```
+
+
+Example of the automated mechanism:
+```ruby
+require 'apipie/rspec/response_validation_helper'
+
+RSpec.describe MyController, :type => :controller, :show_in_doc => true do
+
+describe "GET stuff with response validation" do
+  render_views
+  auto_validate_rendered_views
+
+  it "does something" do
+    get :index, {format: :json}
+  end
+  it "does something else" do
+    get :another_index, {format: :json}
+  end
+end
+
+describe "GET stuff without response validation" do
+  it "does something" do
+    get :index, {format: :json}
+  end
+  it "does something else" do
+    get :another_index, {format: :json}
+  end
+end
+```
+
+Explanation of the implementation approach:
+
+The Apipie Swagger Generator is enhanced to allow extraction of the JSON schema of the response object
+for any controller#action[http-status].  When validation is required, the validator receives the 
+actual response object (along with information about the controller, action and http status code),
+queries the swagger generator to get the schema, and uses the json-schema validator (gem) to validate
+one against the other.
+
+Note that there is a slight complication here:  while supported by JSON-shema, the Swagger 2.0 
+specification does not support a mechanism to declare that fields in the response could be null.  
+As such, for a response that contains `null` fields, if the exact same schema used in the swagger def 
+is passed to the json-schema validator, the validation fails.  To work around this issue, when asked 
+to provide the schema for the purpose of response validation (i.e., not for inclusion in the swagger),
+the Apipie Swagger Generator creates a slightly modified schema which declares null values to be valid.
+