apipie-rails 0.3.6 → 0.9.1

data/CHANGELOG.md

@@ -1,7 +1,251 @@
-===========
  Changelog
 ===========
 
+Also deleted the `Gemfile` that was now a broken symlink.
+please use `export BUNDLE_GEMFILE='gemfiles/Gemfile.rails61'; bundle exec rspec` to run the test suite
+
+## [v0.9.1](https://github.com/Apipie/apipie-rails/tree/v0.9.1) (2023-01-16)
+[Full Changelog](https://github.com/Apipie/apipie-rails/compare/v0.9.0...v0.9.1)
+* [Refactor] Create test cache files under a not version controlled directory [#809](https://github.com/Apipie/apipie-rails/pull/809) (Panos Dalitsouris)
+* [Ruby] Support for Ruby 3.2 [#807](https://github.com/Apipie/apipie-rails/pull/807) (Mathieu Jobin)
+* [Fix] Reverted conditional assignment operators that caused #559 [#806](https://github.com/Apipie/apipie-rails/pull/806) (Nick L. Deltik)
+* [Rubocop] Autocorrect Style/SymbolProc [#793](https://github.com/Apipie/apipie-rails/pull/793) (Rubocop Challenger)
+
+## [v0.9.0](https://github.com/Apipie/apipie-rails/tree/v0.9.0) (2023-01-03)
+[Full Changelog](https://github.com/Apipie/apipie-rails/compare/v0.8.2...v0.9.0)
+* [Refactor] Move Swagger types and warnings under `/generator` namespace [#803](https://github.com/Apipie/apipie-rails/pull/803) (Panos Dalitsouris)
+* [Refactor] Creates `Apipie::MethodDescription::ApisService` [#805](https://github.com/Apipie/apipie-rails/pull/805) (Panos Dalitsouris)
+* [Refactor] Change output folder to `spec/dummy/tmp/` [#804](https://github.com/Apipie/apipie-rails/pull/804) (Panos Dalitsouris)
+* Fix tiny typo in docs [#798](https://github.com/Apipie/apipie-rails/pull/798) (Erik-B. Ernst)
+* Fix Generated docs.json output [#787](https://github.com/Apipie/apipie-rails/pull/787) (Jeremy Liberman)
+* Rubocop Fixes [#775](https://github.com/Apipie/apipie-rails/pull/775), [#778](https://github.com/Apipie/apipie-rails/pull/778), [#780](https://github.com/Apipie/apipie-rails/pull/780), [#790](https://github.com/Apipie/apipie-rails/pull/790), [#783](https://github.com/Apipie/apipie-rails/pull/783), [#785](https://github.com/Apipie/apipie-rails/pull/785) (RuboCop)
+* Remove/clean up dev dependencies and unused rake tasks [#777](https://github.com/Apipie/apipie-rails/pull/777) (Mathieu Jobin)
+    - remove unused rake task
+* Setup Rubocop Challenger [#776](https://github.com/Apipie/apipie-rails/pull/776) (Mathieu Jobin)
+
+## [v0.8.2](https://github.com/Apipie/apipie-rails/tree/v0.8.2) (2022-09-03)
+[Full Changelog](https://github.com/Apipie/apipie-rails/compare/v0.8.1...v0.8.2)
+* Allow custom validators to opt out of allow_blank behavior [#762](https://github.com/Apipie/apipie-rails/pull/762).  (Stephen Hanson)
+* Enforce test coverage, set current 89% as minimum [#764](https://github.com/Apipie/apipie-rails/pull/764). (Mathieu Jobin)
+* Add contributing instructions to readme [#763](https://github.com/Apipie/apipie-rails/pull/763).  (Stephen Hanson)
+* Fix readme formatting [#765](https://github.com/Apipie/apipie-rails/pull/765).  (Stephen Hanson)
+* Adds expected_type to IntegerValidator example [#769](https://github.com/Apipie/apipie-rails/pull/769).  (Jeremy Liberman)
+* Update readme with error handling example [#768](https://github.com/Apipie/apipie-rails/pull/768).  (Jesse Eisenberg)
+* Fix scope incorrectly set to nil when a param_group is used inside an array_of_hash and the param_group is in a different module / controller. [#693](https://github.com/Apipie/apipie-rails/pull/693) [#774](https://github.com/Apipie/apipie-rails/pull/774).  (Omkar Joshi / Oliver Iyer)
+
+## [v0.8.1](https://github.com/Apipie/apipie-rails/tree/v0.8.1) (2022-05-26)
+[Full Changelog](https://github.com/Apipie/apipie-rails/compare/v0.8.0...v0.8.1)
+* Remove warning that came back as of [#752](https://github.com/Apipie/apipie-rails/pull/752). [#761](https://github.com/Apipie/apipie-rails/pull/761) (Jorge Santos / Mathieu Jobin)
+
+## [v0.8.0](https://github.com/Apipie/apipie-rails/tree/v0.8.0) (2022-05-24)
+[Full Changelog](https://github.com/Apipie/apipie-rails/compare/v0.7.2...v0.8.0)
+* Add support for scheme definition in Swagger docs. [#710](https://github.com/Apipie/apipie-rails/pull/710) (Dan Leyden)
+* Add support for Rails 7 [#760](https://github.com/Apipie/apipie-rails/pull/760) (Mathieu Jobin)
+* Clean up code base, removing all trace of unsupported Rails 4.x [#752](https://github.com/Apipie/apipie-rails/pull/752) (Mathieu Jobin)
+* fix: Controller resource set before version [#744](https://github.com/Apipie/apipie-rails/pull/744) (LuukvH)
+* fix: enable swagger generator to add referenced schema for an array of hashes param [#689](https://github.com/Apipie/apipie-rails/pull/689) (Francis San Juan)
+
+## [v0.7.2](https://github.com/Apipie/apipie-rails/tree/v0.7.2) (2022-04-19)
+[Full Changelog](https://github.com/Apipie/apipie-rails/compare/v0.7.1...v0.7.2)
+* Added Korean locale. [#480](https://github.com/Apipie/apipie-rails/pull/480) (Jaehyun Shin ) [#757](https://github.com/Apipie/apipie-rails/pull/757) (Jorge Santos)
+* `Security` Upgraded Bootstrap from 2.0.2 to 2.3.2, JQuery from 1.11.3 to 1.12.4 [#708](https://github.com/Apipie/apipie-rails/pull/708) (Nicolas Waissbluth)
+* Fix ruby2 keyword argument warning [#756](https://github.com/Apipie/apipie-rails/pull/756) (Jorge Santos)
+
+## [v0.7.1](https://github.com/Apipie/apipie-rails/tree/v0.7.1) (2022-04-06)
+[Full Changelog](https://github.com/Apipie/apipie-rails/compare/v0.7.0...v0.7.1)
+* Skip extra parameters while validating the keys. [#690](https://github.com/Apipie/apipie-rails/pull/690) (Omkar Joshi)
+* Support defining security mechanisms for Swagger [#711](https://github.com/Apipie/apipie-rails/pull/711) (Dan Leyden)
+* Update boolean handling of false [#749](https://github.com/Apipie/apipie-rails/pull/749) (Colin Bruce)
+
+Note: Up until and including v0.6.x, apipie-rails was silently ignoring allow_blank == false on String validation.
+when allow_blank is not specified, it default to false. to allow blank strings, you must specify it as a parameter.
+
+Alternatively, if you want to revert to the previous behavior, you can set this configuration option:
+`Apipie.configuration.ignore_allow_blank_false = true`.
+
+## [v0.7.0](https://github.com/Apipie/apipie-rails/tree/v0.7.0) (2022-03-30)
+[Full Changelog](https://github.com/Apipie/apipie-rails/compare/v0.6.0...v0.7.0)
+* ArgumentError (invalid byte sequence in UTF-8) [#746](https://github.com/Apipie/apipie-rails/pull/746) (David Milanese)
+* Fix allow_blank does not work [#733](https://github.com/Apipie/apipie-rails/pull/733) (CHEN Song)
+* Fix schema generation for param descriptions using the array validator in option [#732](https://github.com/Apipie/apipie-rails/pull/732) (Frank Hock)
+* Remove support for Rails 4 and Ruby <= 2.5 [#747](https://github.com/Apipie/apipie-rails/pull/747) (Mathieu Jobin)
+
+## [v0.6.0](https://github.com/Apipie/apipie-rails/tree/v0.6.0) (2022-03-29)
+[Full Changelog](https://github.com/Apipie/apipie-rails/compare/v0.5.20...v0.6.0)
+* Ruby 3.0 fixes [#716](https://github.com/Apipie/apipie-rails/pull/716) (hank-spokeo)
+* only depends on actionpack and activesupport [#741](https://github.com/Apipie/apipie-rails/pull/741) (Mathieu Jobin)
+* language fix, fallback to default locale [#726](https://github.com/Apipie/apipie-rails/pull/726) (Alex Coomans)
+
+## [v0.5.20](https://github.com/Apipie/apipie-rails/tree/v0.5.20) (2022-03-16)
+[Full Changelog](https://github.com/Apipie/apipie-rails/compare/v0.5.19...v0.5.20)
+* Update rel-eng (Oleh Fedorenko)
+* Deprecate travis, run tests on github actions [#740](https://github.com/Apipie/apipie-rails/pull/740) (Mathieu Jobin)
+* Update validator.rb [#739](https://github.com/Apipie/apipie-rails/pull/739) (Dmytro Budnyk)
+* Fix wrong number of arguments for recorder#process [#725](https://github.com/Apipie/apipie-rails/pull/725) (rob mathews)
+* Change "an" to "a" [#723](https://github.com/Apipie/apipie-rails/pull/723) (Naokimi)
+
+## [v0.5.19](https://github.com/Apipie/apipie-rails/tree/v0.5.19) (2021-07-25)
+[Full Changelog](https://github.com/Apipie/apipie-rails/compare/v0.5.18...v0.5.19)
+* Add rel-eng notebook (Oleh Fedorenko)
+* Correct the word parâmentros for brazilian portuguese [#687](https://github.com/Apipie/apipie-rails/pull/687) (Diego Noronha)
+* Fix depreciated file.exists. [#721](https://github.com/Apipie/apipie-rails/pull/721) (Diane Delallée)
+* Fix typo in changelog [#703](https://github.com/Apipie/apipie-rails/pull/703) (Pavel Rodionov)
+* Add rails 6.1 support in doc generation [#702](https://github.com/Apipie/apipie-rails/pull/702) (andrew-newell)
+
+
+[v0.5.18](https://github.com/Apipie/apipie-rails/tree/v0.5.18) (2020-05-20)
+--------
+
+[Full Changelog](https://github.com/Apipie/apipie-rails/compare/v0.5.17...v0.5.18)
+
+- Optional rdoc dependency with lazyload [\#683](https://github.com/Apipie/apipie-rails/pull/683) ([vkrizan](https://github.com/vkrizan))
+
+[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 +314,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/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.
+