grape 1.3.1 → 1.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1711dd2fb0f0c86757c7e73d780907efa87e3da54e0a999a4b45c276b5eec92c
-  data.tar.gz: f5ba49001d1816d92130f70fb1b63ae061d7d9250142605f706d75c207880ad9
+  metadata.gz: fc2b398e9ad95e7e4bb2641bbdaada929d992cd50fb551b56dbafe5f03a75589
+  data.tar.gz: 03765fbe9d5dafb28b531f2a454f06b2ac59d16ea28691036de797b8e64ced06
 SHA512:
-  metadata.gz: 8b2dcf4d4903e3923dd10086a3371258404756cf294cd42c6fb64f3d2520fe7243c0accfe1b68f2e02fbaa85f29396c161d830cde4c5fdedd660b31e8d223a7f
-  data.tar.gz: 88a4d5e9740495430cd28ed1e213d6aafd92895c1b7966bd6358dd6aeb5b2e1f16eac2e14834d63e7791a6d66e16475ef30cdef5e37d10bca0f38f1d1a22c1e4
+  metadata.gz: a078c1c951ff6e5dfee34c78ab04e1f2866be316af23de469db12301ec3c86eb53bcdc9c8ac478aabe02bd3dc34f4772166e49bdf85ef731a051a8d0de73441f
+  data.tar.gz: 7146c097cfced8308f1efb314fb3ace44f30013af8a58a01e9a41a9aca497bd5591c060cabdcc542f25d5660b842548916282541fe869f627538ef51bb083c66

data/CHANGELOG.md

@@ -1,3 +1,83 @@
+### 1.5.1 (2020/11/15)
+
+#### Fixes
+
+* Your contribution here.
+* [#2129](https://github.com/ruby-grape/grape/pull/2129): Fix validation error when Required Array nested inside an optional array, for Multiparam validators - [@dwhenry](https://github.com/dwhenry).
+* [#2128](https://github.com/ruby-grape/grape/pull/2128): Fix validation error when Required Array nested inside an optional array - [@dwhenry](https://github.com/dwhenry).
+* [#2127](https://github.com/ruby-grape/grape/pull/2127): Fix a performance issue with dependent params - [@dnesteryuk](https://github.com/dnesteryuk).
+* [#2126](https://github.com/ruby-grape/grape/pull/2126): Fix warnings about redefined attribute accessors in `AttributeTranslator` - [@samsonjs](https://github.com/samsonjs).
+* [#2121](https://github.com/ruby-grape/grape/pull/2121): Fix 2.7 deprecation warning in validator_factory - [@Legogris](https://github.com/Legogris).
+* [#2115](https://github.com/ruby-grape/grape/pull/2115): Fix declared_params regression with multiple allowed types - [@stanhu](https://github.com/stanhu).
+* [#2123](https://github.com/ruby-grape/grape/pull/2123): Fix 2.7 deprecation warning in middleware/stack - [@Legogris](https://github.com/Legogris).
+
+### 1.5.0 (2020/10/05)
+
+#### Fixes
+
+* [#2104](https://github.com/ruby-grape/grape/pull/2104): Fix Ruby 2.7 keyword deprecation warning - [@stanhu](https://github.com/stanhu).
+* [#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).
+* [#2092](https://github.com/ruby-grape/grape/pull/2092): Correct an example params in Include Missing doc - [@huyvohcmc](https://github.com/huyvohcmc).
+* [#2091](https://github.com/ruby-grape/grape/pull/2091): Fix ruby 2.7 keyword deprecations - [@dim](https://github.com/dim).
+* [#2097](https://github.com/ruby-grape/grape/pull/2097): Skip to set default value unless `meets_dependency?` - [@wanabe](https://github.com/wanabe).
+* [#2096](https://github.com/ruby-grape/grape/pull/2096): Fix redundant dependency check - [@braktar](https://github.com/braktar).
+* [#2096](https://github.com/ruby-grape/grape/pull/2098): Fix nested coercion - [@braktar](https://github.com/braktar).
+* [#2102](https://github.com/ruby-grape/grape/pull/2102): Fix retaining setup blocks when remounting APIs - [@jylamont](https://github.com/jylamont).
+
+### 1.4.0 (2020/07/10)
+
+#### Features
+
+* [#1520](https://github.com/ruby-grape/grape/pull/1520): Un-deprecate stream-like objects - [@urkle](https://github.com/urkle).
+* [#2060](https://github.com/ruby-grape/grape/pull/2060): Drop support for Ruby 2.4 - [@dblock](https://github.com/dblock).
+* [#2060](https://github.com/ruby-grape/grape/pull/2060): Upgraded Rubocop to 0.84.0 - [@dblock](https://github.com/dblock).
+* [#2077](https://github.com/ruby-grape/grape/pull/2077): Simplify logic for defining declared params - [@dnesteryuk](https://github.com/dnesteryuk).
+* [#2076](https://github.com/ruby-grape/grape/pull/2076): Make route information available for hooks when the automatically generated endpoints are invoked - [@anakinj](https://github.com/anakinj).
+
+#### Fixes
+
+* [#2067](https://github.com/ruby-grape/grape/pull/2067): Coerce empty String to `nil` for all primitive types except `String` - [@petekinnecom](https://github.com/petekinnecom).
+* [#2064](https://github.com/ruby-grape/grape/pull/2064): Fix Ruby 2.7 deprecation warning in `Grape::Middleware::Base#initialize` - [@skarger](https://github.com/skarger).
+* [#2072](https://github.com/ruby-grape/grape/pull/2072): Fix `Grape.eager_load!` and `compile!` - [@stanhu](https://github.com/stanhu).
+* [#2084](https://github.com/ruby-grape/grape/pull/2084): Fix memory leak in path normalization - [@fcheung](https://github.com/fcheung).
+
+### 1.3.3 (2020/05/23)
+
+#### Features
+
+* [#2048](https://github.com/ruby-grape/grape/issues/2034): Grape Enterprise support is now available [via TideLift](https://tidelift.com/subscription/request-a-demo?utm_source=rubygems-grape&utm_medium=referral&utm_campaign=enterprise) - [@dblock](https://github.com/dblock).
+* [#2039](https://github.com/ruby-grape/grape/pull/2039): Travis - update rails versions - [@ericproulx](https://github.com/ericproulx).
+* [#2038](https://github.com/ruby-grape/grape/pull/2038): Travis - update ruby versions - [@ericproulx](https://github.com/ericproulx).
+* [#2050](https://github.com/ruby-grape/grape/pull/2050): Refactor route public_send to AttributeTranslator - [@ericproulx](https://github.com/ericproulx).
+
+#### Fixes
+
+* [#2049](https://github.com/ruby-grape/grape/pull/2049): Coerce an empty string to nil in case of the bool type - [@dnesteryuk](https://github.com/dnesteryuk).
+* [#2043](https://github.com/ruby-grape/grape/pull/2043): Modify declared for nested array and hash - [@kadotami](https://github.com/kadotami).
+* [#2040](https://github.com/ruby-grape/grape/pull/2040): Fix a regression with Array of type nil - [@ericproulx](https://github.com/ericproulx).
+* [#2054](https://github.com/ruby-grape/grape/pull/2054): Coercing of nested arrays - [@dnesteryuk](https://github.com/dnesteryuk).
+* [#2050](https://github.com/ruby-grape/grape/pull/2053): Fix broken multiple mounts - [@Jack12816](https://github.com/Jack12816).
+
+### 1.3.2 (2020/04/12)
+
+#### Features
+
+* [#2020](https://github.com/ruby-grape/grape/pull/2020): Reduce array allocation - [@ericproulx](https://github.com/ericproulx).
+* [#2015](https://github.com/ruby-grape/grape/pull/2014): Reduce MatchData allocation - [@ericproulx](https://github.com/ericproulx).
+* [#2014](https://github.com/ruby-grape/grape/pull/2014): Reduce total allocated arrays - [@ericproulx](https://github.com/ericproulx).
+* [#2011](https://github.com/ruby-grape/grape/pull/2011): Reduce total retained regexes - [@ericproulx](https://github.com/ericproulx).
+
+#### Fixes
+
+* [#2033](https://github.com/ruby-grape/grape/pull/2033): Ensure `Float` params are correctly coerced to `BigDecimal` - [@tlconnor](https://github.com/tlconnor).
+* [#2031](https://github.com/ruby-grape/grape/pull/2031): Fix a regression with an array of a custom type - [@dnesteryuk](https://github.com/dnesteryuk).
+* [#2026](https://github.com/ruby-grape/grape/pull/2026): Fix a regression in `coerce_with` when coercion returns `nil` - [@misdoro](https://github.com/misdoro).
+* [#2025](https://github.com/ruby-grape/grape/pull/2025): Fix Decimal type category - [@kdoya](https://github.com/kdoya).
+* [#2019](https://github.com/ruby-grape/grape/pull/2019): Avoid coercing parameter with multiple types to an empty Array - [@stanhu](https://github.com/stanhu).
+
 ### 1.3.1 (2020/03/11)
 
 #### Features
@@ -18,7 +98,8 @@
 * [#1976](https://github.com/ruby-grape/grape/pull/1976): Ensure classes/modules listed for autoload really exist - [@dnesteryuk](https://github.com/dnesteryuk).
 * [#1971](https://github.com/ruby-grape/grape/pull/1971): Fix BigDecimal coercion - [@FlickStuart](https://github.com/FlickStuart).
 * [#1968](https://github.com/ruby-grape/grape/pull/1968): Fix args forwarding in Grape::Middleware::Stack#merge_with for ruby 2.7.0 - [@dm1try](https://github.com/dm1try).
-* [#1988](https://github.com/ruby-grape/grape/pull/1988): Refactored the full_messages method and stop overriding full_message - [@hosseintoussi](https://github.com/hosseintoussi).
+* [#1988](https://github.com/ruby-grape/grape/pull/1988): Refactor the full_messages method and stop overriding full_message - [@hosseintoussi](https://github.com/hosseintoussi).
+* [#1956](https://github.com/ruby-grape/grape/pull/1956): Comply with Rack spec, fix `undefined method [] for nil:NilClass` error when upgrading Rack - [@ioquatix](https://github.com/ioquatix).
 
 ### 1.3.0 (2020/01/11)
 

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2010-2019 Michael Bleigh, Intridea Inc. and Contributors.
+Copyright (c) 2010-2020 Michael Bleigh, Intridea Inc. and Contributors.
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -12,6 +12,7 @@
 - [What is Grape?](#what-is-grape)
 - [Stable Release](#stable-release)
 - [Project Resources](#project-resources)
+- [Grape for Enterprise](#grape-for-enterprise)
 - [Installation](#installation)
 - [Basic Usage](#basic-usage)
 - [Mounting](#mounting)
@@ -141,6 +142,7 @@
     - [format_response.grape](#format_responsegrape)
   - [Monitoring Products](#monitoring-products)
 - [Contributing to Grape](#contributing-to-grape)
+- [Security](#security)
 - [License](#license)
 - [Copyright](#copyright)
 
@@ -154,7 +156,7 @@ content negotiation, versioning and much more.
 
 ## Stable Release
 
-You're reading the documentation for the stable release of Grape, **1.3.1**.
+You're reading the documentation for the stable release of Grape, 1.5.1.
 
 ## Project Resources
 
@@ -163,6 +165,14 @@ You're reading the documentation for the stable release of Grape, **1.3.1**.
 * Need help? Try [Grape Google Group](http://groups.google.com/group/ruby-grape) or [Gitter](https://gitter.im/ruby-grape/grape)
 * [Follow us on Twitter](https://twitter.com/grapeframework)
 
+## Grape for Enterprise
+
+Available as part of the Tidelift Subscription.
+
+The maintainers of Grape are working with Tidelift to deliver commercial support and maintenance. Save time, reduce risk, and improve code health, while paying the maintainers of Grape. Click [here](https://tidelift.com/subscription/request-a-demo?utm_source=rubygems-grape&utm_medium=referral&utm_campaign=enterprise) for more details.
+
+In 2020, we plan to use the money towards gathering Grape contributors for dinner in New York City.
+
 ## Installation
 
 Ruby 2.4 or newer is required.
@@ -338,9 +348,12 @@ class Web < Sinatra::Base
 end
 
 use Rack::Session::Cookie
-run Rack::Cascade.new [API, Web]
+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).
+
+
 ### Rails
 
 Place API files into `app/api`. Rails expects a subdirectory that matches the name of the Ruby module and a file name that matches the name of the class. In our example, the file name location and directory for `Twitter::API` should be `app/api/twitter/api.rb`.
@@ -772,7 +785,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
@@ -805,9 +823,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
 
@@ -835,6 +853,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.
@@ -893,8 +949,10 @@ By default `declared(params)` includes parameters that have `nil` values. If you
 format :json
 
 params do
-  requires :first_name, type: String
-  optional :last_name, type: String
+  requires :user, type: Hash do
+    requires :first_name, type: String
+    optional :last_name, type: String
+  end
 end
 
 post 'users/signup' do
@@ -1047,13 +1105,13 @@ params do
 end
 ```
 
-Note that default values will be passed through to any validation options specified.
-The following example will always fail if `:color` is not explicitly provided.
-
 Default values are eagerly evaluated. Above `:non_random_number` will evaluate to the same
 number for each call to the endpoint of this `params` block. To have the default evaluate
 lazily with each request use a lambda, like `:random_number` above.
 
+Note that default values will be passed through to any validation options specified.
+The following example will always fail if `:color` is not explicitly provided.
+
 ```ruby
 params do
   optional :color, type: String, default: 'blue', values: ['red', 'green']
@@ -1980,10 +2038,10 @@ end
 
 # is NOT the same as
 
-get ':status' do # this makes param[:status] available
+get ':status' do # this makes params[:status] available
 end
 
-# This will make both param[:status_id] and param[:id] available
+# This will make both params[:status_id] and params[:id] available
 
 get 'statuses/:status_id/reviews/:id' do
 end
@@ -3156,17 +3214,19 @@ end
 
 Use `body false` to return `204 No Content` without any data or content-type.
 
-You can also set the response to a file with `file`.
+You can also set the response to a file with `sendfile`. This works with the
+[Rack::Sendfile](https://www.rubydoc.info/gems/rack/Rack/Sendfile) middleware to optimally send
+the file through your web server software.
 
 ```ruby
 class API < Grape::API
   get '/' do
-    file '/path/to/file'
+    sendfile '/path/to/file'
   end
 end
 ```
 
-If you want a file to be streamed using Rack::Chunked, use `stream`.
+To stream a file in chunks use `stream`
 
 ```ruby
 class API < Grape::API
@@ -3176,6 +3236,26 @@ class API < Grape::API
 end
 ```
 
+If you want to stream non-file data use the `stream` method and a `Stream` object.
+This is an object that responds to `each` and yields for each chunk to send to the client.
+Each chunk will be sent as it is yielded instead of waiting for all of the content to be available.
+
+```ruby
+class MyStream
+  def each
+    yield 'part 1'
+    yield 'part 2'
+    yield 'part 3'
+  end
+end
+
+class API < Grape::API
+  get '/' do
+    stream MyStream.new
+  end
+end
+```
+
 ## Authentication
 
 ### Basic and Digest Auth
@@ -3187,14 +3267,13 @@ applies to the current namespace and any children, but not parents.
 ```ruby
 http_basic do |username, password|
   # verify user's password here
-  { 'test' => 'password1' }[username] == password
+  # IMPORTANT: make sure you use a comparison method which isn't prone to a timing attack
 end
 ```
 
 ```ruby
 http_digest({ realm: 'Test Api', opaque: 'app secret' }) do |username|
   # lookup the user's password here
-  { 'user1' => 'password1' }[username]
 end
 ```
 
@@ -3851,7 +3930,7 @@ Grape integrates with following third-party tools:
 * **Librato Metrics** - [grape-librato](https://github.com/seanmoon/grape-librato) gem
 * **[Skylight](https://www.skylight.io/)** - [skylight](https://github.com/skylightio/skylight-ruby) gem, [documentation](https://docs.skylight.io/grape/)
 * **[AppSignal](https://www.appsignal.com)** - [appsignal-ruby](https://github.com/appsignal/appsignal-ruby) gem, [documentation](http://docs.appsignal.com/getting-started/supported-frameworks.html#grape)
-* **[ElasticAPM](https://www.elastic.co/products/apm) - [elastic-apm](https://github.com/elastic/apm-agent-ruby) gem, [documentation](https://www.elastic.co/guide/en/apm/agent/ruby/3.x/getting-started-rack.html#getting-started-grape)
+* **[ElasticAPM](https://www.elastic.co/products/apm)** - [elastic-apm](https://github.com/elastic/apm-agent-ruby) gem, [documentation](https://www.elastic.co/guide/en/apm/agent/ruby/3.x/getting-started-rack.html#getting-started-grape)
 
 ## Contributing to Grape
 
@@ -3860,10 +3939,14 @@ features and discuss issues.
 
 See [CONTRIBUTING](CONTRIBUTING.md).
 
+## Security
+
+See [SECURITY](SECURITY.md) for details.
+
 ## License
 
-MIT License. See LICENSE for details.
+MIT License. See [LICENSE](LICENSE) for details.
 
 ## Copyright
 
-Copyright (c) 2010-2019 Michael Bleigh, Intridea Inc. and Contributors.
+Copyright (c) 2010-2020 Michael Bleigh, Intridea Inc. and Contributors.

data/UPGRADING.md

@@ -1,6 +1,192 @@
 Upgrading Grape
 ===============
 
+### Upgrading to >= 1.5.1
+
+#### Dependent params
+
+If you use [dependent params](https://github.com/ruby-grape/grape#dependent-parameters) with
+`Grape::Extensions::Hash::ParamBuilder`, make sure a parameter to be dependent on is set as a Symbol.
+If a String is given, a parameter that other parameters depend on won't be found even if it is present.
+
+_Correct_:
+```ruby
+given :matrix do
+  # dependent params
+end
+```
+
+_Wrong_:
+```ruby
+given 'matrix' do
+  # dependent params
+end
+```
+
+### Upgrading to >= 1.5.0
+
+Prior to 1.3.3, the `declared` helper would always return the complete params structure if `include_missing=true` was set. In 1.3.3 a regression was introduced such that a missing Hash with or without nested parameters would always resolve to `{}`.
+
+In 1.5.0 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 children will resolve to a Hash with keys for each declared child.
+* Hash params with no children will resolve to `{}`.
+* Set params will resolve to `Set.new`.
+* Array params will resolve to `[]`.
+* All other params will resolve to `nil`.
+
+#### Example
+
+```ruby
+class Api < Grape::API
+  params do
+    optional :outer, type: Hash do
+      optional :inner, type: Hash do
+        optional :value, type: String
+      end
+    end
+  end
+  get 'example' do
+    declared(params, include_missing: true)
+  end
+end
+```
+
+```
+get '/example'
+# 1.3.3 = {}
+# 1.5.0 = {outer: {inner: {value:null}}}
+```
+
+For more information see [#2103](https://github.com/ruby-grape/grape/pull/2103).
+
+### Upgrading to >= 1.4.0
+
+#### Reworking stream and file and un-deprecating stream like-objects
+
+Previously in 0.16 stream-like objects were deprecated. This release restores their functionality for use-cases other than file streaming.
+
+This release deprecated `file` in favor of `sendfile` to better document its purpose.
+
+To deliver a file via the Sendfile support in your web server and have the Rack::Sendfile middleware enabled. See [`Rack::Sendfile`](https://www.rubydoc.info/gems/rack/Rack/Sendfile).
+```ruby
+class API < Grape::API
+  get '/' do
+    sendfile '/path/to/file'
+  end
+end
+```
+
+Use `stream` to stream file content in chunks.
+
+```ruby
+class API < Grape::API
+  get '/' do
+    stream '/path/to/file'
+  end
+end
+```
+
+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
+  attr_accessor :result
+
+  def initialize(query)
+    @result = query
+  end
+
+  def each
+    yield '['
+    # Do paginated DB fetches and return each page formatted
+    first = false
+    result.find_in_batches do |records|
+      yield process_records(records, first)
+      first = false
+    end
+    yield ']'
+  end
+
+  def process_records(records, first)
+    buffer = +''
+    buffer << ',' unless first
+    buffer << records.map(&:to_json).join(',')
+    buffer
+  end
+end
+
+class API < Grape::API
+  get '/' do
+    stream MyObject.new(Sprocket.all)
+  end
+end
+```
+
+### Upgrading to >= 1.3.3
+
+#### Nil values for structures
+
+Nil values always been a special case when dealing with types especially with the following structures:
+
+- Array
+- Hash
+- Set
+
+The behavior for these structures has change through out the latest releases. For example:
+
+```ruby
+class Api < Grape::API
+  params do
+    require :my_param, type: Array[Integer]
+  end
+
+  get 'example' do
+     params[:my_param]
+  end
+  get '/example', params: { my_param: nil }
+  # 1.3.1 = []
+  # 1.3.2 = nil
+end
+```
+
+For now on, `nil` values stay `nil` values for all types, including arrays, sets and hashes.
+
+If you want to have the same behavior as 1.3.1, apply a `default` validator:
+
+```ruby
+class Api < Grape::API
+  params do
+    require :my_param, type: Array[Integer], default: []
+  end
+
+  get 'example' do
+     params[:my_param]
+  end
+  get '/example', params: { my_param: nil } # => []
+end
+```
+
+#### Default validator
+
+Default validator is now applied for `nil` values.
+
+```ruby
+class Api < Grape::API
+  params do
+    requires :my_param, type: Integer, default: 0
+  end
+
+  get 'example' do
+     params[:my_param]
+  end
+  get '/example', params: { my_param: nil } #=> before: nil, after: 0
+end
+```
+
 ### Upgrading to >= 1.3.0
 
 #### Ruby
@@ -9,38 +195,87 @@ After adding dry-types, Ruby 2.4 or newer is required.
 
 #### Coercion
 
-[Virtus](https://github.com/solnic/virtus) has been replaced by [dry-types](https://dry-rb.org/gems/dry-types/1.2/) for parameter coercion. If your project depends on Virtus, explicitly add it to your `Gemfile`. Also, if Virtus is used for defining custom types
+[Virtus](https://github.com/solnic/virtus) has been replaced by [dry-types](https://dry-rb.org/gems/dry-types/1.2/) for parameter coercion. If your project depends on Virtus outside of Grape, explicitly add it to your `Gemfile`.
+
+Here's an example of how to migrate a custom type from Virtus to dry-types:
 
 ```ruby
-class User
-  include Virtus.model
+# Legacy Grape parser
+class SecureUriType < Virtus::Attribute
+  def coerce(input)
+    URI.parse value
+  end
 
-  attribute :id, Integer
-  attribute :name, String
+  def value_coerced?(input)
+    value.is_a? String
+  end
 end
 
-# somewhere in your API
 params do
-  requires :user, type: User
+  requires :secure_uri, type: SecureUri
 end
 ```
 
-Add a class-level `parse` method to the model:
+To use dry-types, we need to:
 
-```ruby
-class User
-  include Virtus.model
+1. Remove the inheritance of `Virtus::Attribute`
+1. Rename `coerce` to `self.parse`
+1. Rename `value_coerced?` to `self.parsed?`
 
-  attribute :id, Integer
-  attribute :name, String
+The custom type must have a class-level `parse` method to the model. A class-level `parsed?` is needed if the parsed type differs from the defined type. In the example below, since `SecureUri` is not the same as `URI::HTTPS`, `self.parsed?` is needed:
 
-  def self.parse(attrs)
-    new(attrs)
+```ruby
+# New dry-types parser
+class SecureUri
+  def self.parse(value)
+    URI.parse value
+  end
+
+  def self.parsed?(value)
+    value.is_a? URI::HTTPS
   end
 end
+
+params do
+  requires :secure_uri, type: SecureUri
+end
 ```
 
-Custom types which don't depend on Virtus don't require any changes.
+#### Coercing to `FalseClass` or `TrueClass` no longer works
+
+Previous Grape versions allowed this, though it wasn't documented:
+
+```ruby
+requires :true_value, type: TrueClass
+requires :bool_value, types: [FalseClass, TrueClass]
+```
+
+This is no longer supported, if you do this, your values will never be valid. Instead you should do this:
+
+```ruby
+requires :true_value, type: Boolean # in your endpoint you should validate if this is actually `true`
+requires :bool_value, type: Boolean
+```
+
+#### Ensure that Array types have explicit coercions
+
+Unlike Virtus, dry-types does not perform any implict coercions. If you have any uses of `Array[String]`, `Array[Integer]`, etc. be sure they use a `coerce_with` block. For example:
+
+```ruby
+requires :values, type: Array[String]
+```
+
+It's quite common to pass a comma-separated list, such as `tag1,tag2` as `values`. Previously Virtus would implicitly coerce this to `Array(values)` so that `["tag1,tag2"]` would pass the type checks, but with `dry-types` the values are no longer coerced for you. To fix this, you might do:
+
+```ruby
+requires :values, type: Array[String], coerce_with: ->(val) { val.split(',').map(&:strip) }
+```
+
+Likewise, for `Array[Integer]`, you might do:
+
+```ruby
+requires :values, type: Array[Integer], coerce_with: ->(val) { val.split(',').map(&:strip).map(&:to_i) }
+```
 
 For more information see [#1920](https://github.com/ruby-grape/grape/pull/1920).
 
@@ -97,12 +332,9 @@ In order to make obtaining the name of a mounted class simpler, we've delegated
 
 ##### Patching the class
 
-In an effort to make APIs re-mountable, The class `Grape::API` no longer refers to an API instance,
-rather, what used to be `Grape::API` is now `Grape::API::Instance` and `Grape::API` was replaced
-with a class that can contain several instances of `Grape::API`.
+In an effort to make APIs re-mountable, The class `Grape::API` no longer refers to an API instance, rather, what used to be `Grape::API` is now `Grape::API::Instance` and `Grape::API` was replaced with a class that can contain several instances of `Grape::API`.
 
-This changes were done in such a way that no code-changes should be required.
-However, if experiencing problems, or relying on private methods and internal behaviour too deeply, it is possible to restore the prior behaviour by replacing the references from `Grape::API` to `Grape::API::Instance`.
+This changes were done in such a way that no code-changes should be required. However, if experiencing problems, or relying on private methods and internal behaviour too deeply, it is possible to restore the prior behaviour by replacing the references from `Grape::API` to `Grape::API::Instance`.
 
 Note, this is particularly relevant if you are opening the class `Grape::API` for modification.
 
@@ -125,15 +357,20 @@ end
 
 After the patch, the mounted API is no longer a Named class inheriting from `Grape::API`, it is an anonymous class
 which inherit from `Grape::API::Instance`.
+
 What this means in practice, is:
+
 - Generally: you can access the named class from the instance calling the getter `base`.
-- In particular: If you need the `name`, you can use `base`.`name`
+- In particular: If you need the `name`, you can use `base`.`name`.
 
 **Deprecated**
+
 ```ruby
   payload[:endpoint].options[:for].name
 ```
+
 **New**
+
 ```ruby
   payload[:endpoint].options[:for].base.name
 ```
@@ -224,8 +461,7 @@ See [#1610](https://github.com/ruby-grape/grape/pull/1610) for more information.
 
 #### The `except`, `except_message`, and `proc` options of the `values` validator are deprecated.
 
-The new `except_values` validator should be used in place of the `except` and `except_message` options of
-the `values` validator.
+The new `except_values` validator should be used in place of the `except` and `except_message` options of the `values` validator.
 
 Arity one Procs may now be used directly as the `values` option to explicitly test param values.
 
@@ -301,9 +537,7 @@ get '/example' #=> before: 405, after: 404
 
 #### Removed param processing from built-in OPTIONS handler
 
-When a request is made to the built-in `OPTIONS` handler, only the `before` and `after`
-callbacks associated with the resource will be run.  The `before_validation` and
-`after_validation` callbacks and parameter validations will be skipped.
+When a request is made to the built-in `OPTIONS` handler, only the `before` and `after` callbacks associated with the resource will be run.  The `before_validation` and `after_validation` callbacks and parameter validations will be skipped.
 
 See [#1505](https://github.com/ruby-grape/grape/pull/1505) for more information.
 
@@ -324,8 +558,7 @@ See [#1510](https://github.com/ruby-grape/grape/pull/1510) for more information.
 
 #### The default status code for DELETE is now 204 instead of 200.
 
-Breaking change: Sets the default response status code for a delete request to 204.
-A status of 204 makes the response more distinguishable and therefore easier to handle on the client side, particularly because a DELETE request typically returns an empty body as the resource was deleted or voided.
+Breaking change: Sets the default response status code for a delete request to 204. A status of 204 makes the response more distinguishable and therefore easier to handle on the client side, particularly because a DELETE request typically returns an empty body as the resource was deleted or voided.
 
 To achieve the old behavior, one has to set it explicitly:
 ```ruby
@@ -503,18 +736,14 @@ See [#1114](https://github.com/ruby-grape/grape/pull/1114) for more information.
 
 #### Bypasses formatters when status code indicates no content
 
-To be consistent with rack and it's handling of standard responses
-associated with no content, both default and custom formatters will now
+To be consistent with rack and it's handling of standard responses associated with no content, both default and custom formatters will now
 be bypassed when processing responses for status codes defined [by rack](https://github.com/rack/rack/blob/master/lib/rack/utils.rb#L567)
 
 See [#1190](https://github.com/ruby-grape/grape/pull/1190) for more information.
 
 #### Redirects respond as plain text with message
 
-`#redirect` now uses `text/plain` regardless of whether that format has
-been enabled. This prevents formatters from attempting to serialize the
-message body and allows for a descriptive message body to be provided - and
-optionally overridden - that better fulfills the theme of the HTTP spec.
+`#redirect` now uses `text/plain` regardless of whether that format has been enabled. This prevents formatters from attempting to serialize the message body and allows for a descriptive message body to be provided - and optionally overridden - that better fulfills the theme of the HTTP spec.
 
 See [#1194](https://github.com/ruby-grape/grape/pull/1194) for more information.
 
@@ -548,10 +777,7 @@ end
 
 See [#1029](https://github.com/ruby-grape/grape/pull/1029) for more information.
 
-There is a known issue because of this change. When Grape is used with an older
-than 1.2.4 version of [warden](https://github.com/hassox/warden) there may be raised
-the following exception having the [rack-mount](https://github.com/jm/rack-mount) gem's
-lines as last ones in the backtrace:
+There is a known issue because of this change. When Grape is used with an older than 1.2.4 version of [warden](https://github.com/hassox/warden) there may be raised the following exception having the [rack-mount](https://github.com/jm/rack-mount) gem's lines as last ones in the backtrace:
 
 ```
 NoMethodError: undefined method `[]' for nil:NilClass