Update README / CHANGELOG / UPGRADING

Author: Tim Connor

CHANGELOG.md

@@ -7,6 +7,7 @@
 #### Fixes
 
 * Your contribution here.
+* [#2103](https://github.com/ruby-grape/grape/pull/2103): Ensure complete declared params structure is present - [@tlconnor](https://github.com/tlconnor).
 * [#2099](https://github.com/ruby-grape/grape/pull/2099): Added truffleruby to Travis-CI - [@gogainda](https://github.com/gogainda).
 * [#2089](https://github.com/ruby-grape/grape/pull/2089): Specify order of mounting Grape with Rack::Cascade in README - [@jonmchan](https://github.com/jonmchan).
 * [#2083](https://github.com/ruby-grape/grape/pull/2083): Set `Cache-Control` header only for streamed responses - [@stanhu](https://github.com/stanhu).

README.md

@@ -353,7 +353,7 @@ use Rack::Session::Cookie
 run Rack::Cascade.new [Web, API]
 ```
 
-Note that order of loading apps using `Rack::Cascade` matters. The grape application must be last if you want to raise custom 404 errors from grape (such as `error!('Not Found',404)`). If the grape application is not last and returns 404 or 405 response, [cascade utilizes that as a signal to try the next app](https://www.rubydoc.info/gems/rack/Rack/Cascade). This may lead to undesirable behavior showing the [wrong 404 page from the wrong app](https://github.com/ruby-grape/grape/issues/1515). 
+Note that order of loading apps using `Rack::Cascade` matters. The grape application must be last if you want to raise custom 404 errors from grape (such as `error!('Not Found',404)`). If the grape application is not last and returns 404 or 405 response, [cascade utilizes that as a signal to try the next app](https://www.rubydoc.info/gems/rack/Rack/Cascade). This may lead to undesirable behavior showing the [wrong 404 page from the wrong app](https://github.com/ruby-grape/grape/issues/1515).
 
 
 ### Rails
@@ -787,7 +787,12 @@ Available parameter builders are `Grape::Extensions::Hash::ParamBuilder`, `Grape
 
 ### Declared
 
-Grape allows you to access only the parameters that have been declared by your `params` block. It filters out the params that have been passed, but are not allowed. Consider the following API endpoint:
+Grape allows you to access only the parameters that have been declared by your `params` block. It will:
+
+  * Filter out the params that have been passed, but are not allowed.
+  * Include any optional params that are declared but not passed.
+
+Consider the following API endpoint:
 
 ````ruby
 format :json
@@ -820,9 +825,9 @@ Once we add parameters requirements, grape will start returning only the declare
 format :json
 
 params do
-  requires :user, type: Hash do
-    requires :first_name, type: String
-    requires :last_name, type: String
+  optional :user, type: Hash do
+    optional :first_name, type: String
+    optional :last_name, type: String
   end
 end
 
@@ -850,6 +855,44 @@ curl -X POST -H "Content-Type: application/json" localhost:9292/users/signup -d
 }
 ````
 
+Missing params that are declared as type `Hash` or `Array` will be included.
+
+````ruby
+format :json
+
+params do
+  optional :user, type: Hash do
+    optional :first_name, type: String
+    optional :last_name, type: String
+  end
+  optional :widgets, type: Array
+end
+
+post 'users/signup' do
+  { 'declared_params' => declared(params) }
+end
+````
+
+**Request**
+
+````bash
+curl -X POST -H "Content-Type: application/json" localhost:9292/users/signup -d '{}'
+````
+
+**Response**
+
+````json
+{
+  "declared_params": {
+    "user": {
+      "first_name": null,
+      "last_name": null
+    },
+    "widgets": []
+  }
+}
+````
+
 The returned hash is an `ActiveSupport::HashWithIndifferentAccess`.
 
 The `#declared` method is not available to `before` filters, as those are evaluated prior to parameter coercion.

UPGRADING.md

@@ -1,6 +1,19 @@
 Upgrading Grape
 ===============
 
+### Upgrading to >= 1.4.1
+
+Previous to 1.3.3, the `declared` helper would always return the complete params structure if `include_missing=true` was set. In 1.3.3 the behavior was changed, so a missing Hash with or without nested parameters would always resolve as `{}`.
+
+In 1.4.1 this behavior is reverted, so the whole params structure will always be available via `declared`, regardless of whether any params are passed.
+
+The following rules now apply to the `declared` helper when params are missing and `include_missing=true`:
+
+* Hash params with childern will resolve as a hash with keys for each declared child.
+* Hash params with no children will resolve as `{}`.
+* Array params will resolve as `[]`.
+* All other params will resolve as `null`.
+
 ### Upgrading to >= 1.4.0
 
 #### Reworking stream and file and un-deprecating stream like-objects
@@ -28,17 +41,17 @@ class API < Grape::API
 end
 ```
 
-Or use `stream` to stream other kinds of content. In the following example a streamer class 
+Or use `stream` to stream other kinds of content. In the following example a streamer class
 streams paginated data from a database.
 
 ```ruby
-class MyObject     
+class MyObject
   attr_accessor :result
 
   def initialize(query)
     @result = query
   end
-  
+
   def each
     yield '['
     # Do paginated DB fetches and return each page formatted
@@ -47,7 +60,7 @@ class MyObject
       yield process_records(records, first)
       first = false
     end
-    yield ']'  
+    yield ']'
   end
 
   def process_records(records, first)