grape 1.0.0 → 1.6.0

data/README.md

@@ -1,12 +1,10 @@
 ![grape logo](grape.png)
 
 [![Gem Version](https://badge.fury.io/rb/grape.svg)](http://badge.fury.io/rb/grape)
-[![Build Status](https://travis-ci.org/ruby-grape/grape.svg?branch=master)](https://travis-ci.org/ruby-grape/grape)
-[![Dependency Status](https://gemnasium.com/ruby-grape/grape.svg)](https://gemnasium.com/ruby-grape/grape)
+[![Build Status](https://github.com/ruby-grape/grape/workflows/test/badge.svg?branch=master)](https://github.com/ruby-grape/grape/actions)
 [![Code Climate](https://codeclimate.com/github/ruby-grape/grape.svg)](https://codeclimate.com/github/ruby-grape/grape)
 [![Coverage Status](https://coveralls.io/repos/github/ruby-grape/grape/badge.svg?branch=master)](https://coveralls.io/github/ruby-grape/grape?branch=master)
-[![Inline docs](http://inch-ci.org/github/ruby-grape/grape.svg)](http://inch-ci.org/github/ruby-grape/grape)
-[![git.legal](https://git.legal/projects/1364/badge.svg "Number of libraries approved")](https://git.legal/projects/1364)
+[![Inline docs](https://inch-ci.org/github/ruby-grape/grape.svg)](https://inch-ci.org/github/ruby-grape/grape)
 [![Join the chat at https://gitter.im/ruby-grape/grape](https://badges.gitter.im/ruby-grape/grape.svg)](https://gitter.im/ruby-grape/grape?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 
 ## Table of Contents
@@ -14,41 +12,76 @@
 - [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)
+  - [All](#all)
   - [Rack](#rack)
   - [ActiveRecord without Rails](#activerecord-without-rails)
+    - [Rails 4](#rails-4)
+    - [Rails 5+](#rails-5)
   - [Alongside Sinatra (or other frameworks)](#alongside-sinatra-or-other-frameworks)
   - [Rails](#rails)
+    - [Rails < 5.2](#rails--52)
+    - [Rails 6.0](#rails-60)
   - [Modules](#modules)
+- [Remounting](#remounting)
+  - [Mount Configuration](#mount-configuration)
 - [Versioning](#versioning)
   - [Path](#path)
   - [Header](#header)
   - [Accept-Version Header](#accept-version-header)
   - [Param](#param)
 - [Describing Methods](#describing-methods)
+- [Configuration](#configuration)
 - [Parameters](#parameters)
   - [Params Class](#params-class)
   - [Declared](#declared)
+  - [Include Parent Namespaces](#include-parent-namespaces)
   - [Include Missing](#include-missing)
 - [Parameter Validation and Coercion](#parameter-validation-and-coercion)
   - [Supported Parameter Types](#supported-parameter-types)
   - [Integer/Fixnum and Coercions](#integerfixnum-and-coercions)
   - [Custom Types and Coercions](#custom-types-and-coercions)
   - [Multipart File Parameters](#multipart-file-parameters)
-  - [First-Class `JSON` Types](#first-class-json-types)
+  - [First-Class JSON Types](#first-class-json-types)
   - [Multiple Allowed Types](#multiple-allowed-types)
   - [Validation of Nested Parameters](#validation-of-nested-parameters)
   - [Dependent Parameters](#dependent-parameters)
   - [Group Options](#group-options)
+  - [Renaming](#renaming)
   - [Built-in Validators](#built-in-validators)
+    - [allow_blank](#allow_blank)
+    - [values](#values)
+    - [except_values](#except_values)
+    - [same_as](#same_as)
+    - [regexp](#regexp)
+    - [mutually_exclusive](#mutually_exclusive)
+    - [exactly_one_of](#exactly_one_of)
+    - [at_least_one_of](#at_least_one_of)
+    - [all_or_none_of](#all_or_none_of)
+    - [Nested mutually_exclusive, exactly_one_of, at_least_one_of, all_or_none_of](#nested-mutually_exclusive-exactly_one_of-at_least_one_of-all_or_none_of)
   - [Namespace Validation and Coercion](#namespace-validation-and-coercion)
   - [Custom Validators](#custom-validators)
   - [Validation Errors](#validation-errors)
   - [I18n](#i18n)
-  - [Custom Validation Messages](#custom-validation-messages)
+  - [Custom Validation messages](#custom-validation-messages)
+    - [presence, allow_blank, values, regexp](#presence-allow_blank-values-regexp)
+    - [same_as](#same_as-1)
+    - [all_or_none_of](#all_or_none_of-1)
+    - [mutually_exclusive](#mutually_exclusive-1)
+    - [exactly_one_of](#exactly_one_of-1)
+    - [at_least_one_of](#at_least_one_of-1)
+    - [Coerce](#coerce)
+    - [With Lambdas](#with-lambdas)
+    - [Pass symbols for i18n translations](#pass-symbols-for-i18n-translations)
+    - [Overriding Attribute Names](#overriding-attribute-names)
+    - [With Default](#with-default)
 - [Headers](#headers)
+  - [Request](#request)
+    - [Header Case Handling](#header-case-handling)
+  - [Response](#response)
 - [Routes](#routes)
 - [Helpers](#helpers)
 - [Path Helpers](#path-helpers)
@@ -62,6 +95,9 @@
   - [Default Error HTTP Status Code](#default-error-http-status-code)
   - [Handling 404](#handling-404)
 - [Exception Handling](#exception-handling)
+    - [Rescuing exceptions inside namespaces](#rescuing-exceptions-inside-namespaces)
+    - [Unrescuable Exceptions](#unrescuable-exceptions)
+    - [Exceptions that should be rescued explicitly](#exceptions-that-should-be-rescued-explicitly)
   - [Rails 3.x](#rails-3x)
 - [Logging](#logging)
 - [API Formats](#api-formats)
@@ -77,9 +113,11 @@
   - [Active Model Serializers](#active-model-serializers)
 - [Sending Raw or No Data](#sending-raw-or-no-data)
 - [Authentication](#authentication)
+  - [Basic and Digest Auth](#basic-and-digest-auth)
+  - [Register custom middleware for authentication](#register-custom-middleware-for-authentication)
 - [Describing and Inspecting an API](#describing-and-inspecting-an-api)
 - [Current Route and Endpoint](#current-route-and-endpoint)
-- [Before and After](#before-and-after)
+- [Before, After and Finally](#before-after-and-finally)
 - [Anchoring](#anchoring)
 - [Using Custom Middleware](#using-custom-middleware)
   - [Grape Middleware](#grape-middleware)
@@ -87,15 +125,26 @@
   - [Remote IP](#remote-ip)
 - [Writing Tests](#writing-tests)
   - [Writing Tests with Rack](#writing-tests-with-rack)
+    - [RSpec](#rspec)
+    - [Airborne](#airborne)
+    - [MiniTest](#minitest)
   - [Writing Tests with Rails](#writing-tests-with-rails)
+    - [RSpec](#rspec-1)
+    - [MiniTest](#minitest-1)
   - [Stubbing Helpers](#stubbing-helpers)
 - [Reloading API Changes in Development](#reloading-api-changes-in-development)
   - [Reloading in Rack Applications](#reloading-in-rack-applications)
   - [Reloading in Rails Applications](#reloading-in-rails-applications)
 - [Performance Monitoring](#performance-monitoring)
   - [Active Support Instrumentation](#active-support-instrumentation)
+    - [endpoint_run.grape](#endpoint_rungrape)
+    - [endpoint_render.grape](#endpoint_rendergrape)
+    - [endpoint_run_filters.grape](#endpoint_run_filtersgrape)
+    - [endpoint_run_validators.grape](#endpoint_run_validatorsgrape)
+    - [format_response.grape](#format_responsegrape)
   - [Monitoring Products](#monitoring-products)
 - [Contributing to Grape](#contributing-to-grape)
+- [Security](#security)
 - [License](#license)
 - [Copyright](#copyright)
 
@@ -109,17 +158,28 @@ content negotiation, versioning and much more.
 
 ## Stable Release
 
-You're reading the documentation for the stable release of Grape, 1.0.0.
+You're reading the documentation for the stable release of Grape, **1.6.0**.
 Please read [UPGRADING](UPGRADING.md) when upgrading from a previous version.
 
 ## Project Resources
 
 * [Grape Website](http://www.ruby-grape.org)
+* [Documentation](http://www.rubydoc.info/gems/grape)
 * 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.
+
 Grape is available as a gem, to install it just install the gem:
 
     gem install grape
@@ -167,7 +227,7 @@ module Twitter
 
       desc 'Return a status.'
       params do
-        requires :id, type: Integer, desc: 'Status id.'
+        requires :id, type: Integer, desc: 'Status ID.'
       end
       route_param :id do
         get do
@@ -215,6 +275,17 @@ end
 
 ## Mounting
 
+### All
+
+
+By default Grape will compile the routes on the first route, it is possible to pre-load routes using the `compile!` method.
+
+```ruby
+Twitter::API.compile!
+```
+
+This can be added to your `config.ru` (if using rackup), `application.rb` (if using rails), or any file that loads your server.
+
 ### Rack
 
 The above sample creates a Rack application that can be run from a rackup `config.ru` file
@@ -224,6 +295,13 @@ with `rackup`:
 run Twitter::API
 ```
 
+(With pre-loading you can use)
+
+```ruby
+Twitter::API.compile!
+run Twitter::API
+```
+
 And would respond to the following routes:
 
     GET /api/statuses/public_timeline
@@ -240,13 +318,21 @@ Grape will also automatically respond to HEAD and OPTIONS for all GET, and just
 If you want to use ActiveRecord within Grape, you will need to make sure that ActiveRecord's connection pool
 is handled correctly.
 
+#### Rails 4
+
 The easiest way to achieve that is by using ActiveRecord's `ConnectionManagement` middleware in your
 `config.ru` before mounting Grape, e.g.:
 
 ```ruby
 use ActiveRecord::ConnectionAdapters::ConnectionManagement
+```
 
-run Twitter::API
+#### Rails 5+
+
+Use [otr-activerecord](https://github.com/jhollinger/otr-activerecord) as follows:
+
+```ruby
+use OTR::ActiveRecord::ConnectionManagement
 ```
 
 ### Alongside Sinatra (or other frameworks)
@@ -273,13 +359,24 @@ 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`.
 
+Modify `config/routes`:
+
+```ruby
+mount Twitter::API => '/'
+```
+
+#### Rails < 5.2
+
 Modify `application.rb`:
 
 ```ruby
@@ -287,21 +384,18 @@ config.paths.add File.join('app', 'api'), glob: File.join('**', '*.rb')
 config.autoload_paths += Dir[Rails.root.join('app', 'api', '*')]
 ```
 
-Modify `config/routes`:
+See [below](#reloading-api-changes-in-development) for additional code that enables reloading of API changes in development.
 
-```ruby
-mount Twitter::API => '/'
-```
+#### Rails 6.0
 
-Additionally, if the version of your Rails is 4.0+ and the application uses the default model layer of ActiveRecord, you will want to use the [hashie-forbidden_attributes gem](https://github.com/Maxim-Filimonov/hashie-forbidden_attributes). This gem disables the security feature of `strong_params` at the model layer, allowing you the use of Grape's own params validation instead.
+For Rails versions greater than 6.0.0.beta2, `Zeitwerk` autoloader is the default for CRuby. By default `Zeitwerk` inflects `api` as `Api` instead of `API`. To make our example work, you need to uncomment the lines at the bottom of `config/initializers/inflections.rb`, and add `API` as an acronym:
 
 ```ruby
-# Gemfile
-gem 'hashie-forbidden_attributes'
+ActiveSupport::Inflector.inflections(:en) do |inflect|
+  inflect.acronym 'API'
+end
 ```
 
-See [below](#reloading-api-changes-in-development) for additional code that enables reloading of API changes in development.
-
 ### Modules
 
 You can mount multiple API implementations inside another one. These don't have to be
@@ -335,6 +429,131 @@ class Twitter::API < Grape::API
 end
 ```
 
+## Remounting
+
+You can mount the same endpoints in two different locations.
+
+```ruby
+class Voting::API < Grape::API
+  namespace 'votes' do
+    get do
+      # Your logic
+    end
+
+    post do
+      # Your logic
+    end
+  end
+end
+
+class Post::API < Grape::API
+  mount Voting::API
+end
+
+class Comment::API < Grape::API
+  mount Voting::API
+end
+```
+
+Assuming that the post and comment endpoints are mounted in `/posts` and `/comments`, you should now be able to do `get /posts/votes`, `post /posts/votes`, `get /comments/votes` and `post /comments/votes`.
+
+### Mount Configuration
+
+You can configure remountable endpoints to change how they behave according to where they are mounted.
+
+```ruby
+class Voting::API < Grape::API
+  namespace 'votes' do
+    desc "Vote for your #{configuration[:votable]}"
+    get do
+      # Your logic
+    end
+  end
+end
+
+class Post::API < Grape::API
+  mount Voting::API, with: { votable: 'posts' }
+end
+
+class Comment::API < Grape::API
+  mount Voting::API, with: { votable: 'comments' }
+end
+```
+
+Note that if you're passing a hash as the first parameter to `mount`, you will need to explicitly put `()` around parameters:
+```ruby
+# good
+mount({ ::Some::Api => '/some/api' }, with: { condition: true })
+
+# bad
+mount ::Some::Api => '/some/api', with: { condition: true }
+```
+
+You can access `configuration` on the class (to use as dynamic attributes), inside blocks (like namespace)
+
+If you want logic happening given on an `configuration`, you can use the helper `given`.
+
+```ruby
+class ConditionalEndpoint::API < Grape::API
+  given configuration[:some_setting] do
+    get 'mount_this_endpoint_conditionally' do
+      configuration[:configurable_response]
+    end
+  end
+end
+```
+
+If you want a block of logic running every time an endpoint is mounted (within which you can access the `configuration` Hash)
+
+
+```ruby
+class ConditionalEndpoint::API < Grape::API
+  mounted do
+    YourLogger.info "This API was mounted at: #{Time.now}"
+
+    get configuration[:endpoint_name] do
+      configuration[:configurable_response]
+    end
+  end
+end
+```
+
+More complex results can be achieved by using `mounted` as an expression within which the `configuration` is already evaluated as a Hash.
+
+```ruby
+class ExpressionEndpointAPI < Grape::API
+  get(mounted { configuration[:route_name] || 'default_name' }) do
+    # some logic
+  end
+end
+```
+
+```ruby
+class BasicAPI < Grape::API
+  desc 'Statuses index' do
+    params: mounted { configuration[:entity] || API::Entities::Status }.documentation
+  end
+  params do
+    requires :all, using: mounted { configuration[:entity] || API::Entities::Status }.documentation
+  end
+  get '/statuses' do
+    statuses = Status.all
+    type = current_user.admin? ? :full : :default
+    present statuses, with: mounted { configuration[:entity] || API::Entities::Status }, type: type
+  end
+end
+
+class V1 < Grape::API
+  version 'v1'
+  mount BasicAPI, with: { entity: mounted { configuration[:entity] || API::Enitities::Status } }
+end
+
+class V2 < Grape::API
+  version 'v2'
+  mount BasicAPI, with: { entity: mounted { configuration[:entity] || API::Enitities::V2::Status } }
+end
+```
+
 ## Versioning
 
 There are four strategies in which clients can reach your API's endpoints: `:path`,
@@ -415,10 +634,13 @@ version 'v1', using: :param, parameter: 'v'
 
 ## Describing Methods
 
-You can add a description to API methods and namespaces.
+You can add a description to API methods and namespaces. The description would be used by [grape-swagger][grape-swagger] to generate swagger compliant documentation.
+
+Note: Description block is only for documentation and won't affects API behavior.
 
 ```ruby
 desc 'Returns your public timeline.' do
+  summary 'summary'
   detail 'more details'
   params  API::Entities::Status.documentation
   success API::Entities::Entity
@@ -432,7 +654,13 @@ desc 'Returns your public timeline.' do
             description: 'Not really needed',
             required: false
           }
-
+  hidden false
+  deprecated false
+  is_array true
+  nickname 'nickname'
+  produces ['application/json']
+  consumes ['application/json']
+  tags ['tag1', 'tag2']
 end
 get :public_timeline do
   Status.limit(20)
@@ -445,6 +673,43 @@ end
 * `failure`: (former http_codes) A definition of the used failure HTTP Codes and Entities
 * `named`: A helper to give a route a name and find it with this name in the documentation Hash
 * `headers`: A definition of the used Headers
+* Other options can be found in [grape-swagger][grape-swagger]
+
+[grape-swagger]: https://github.com/ruby-grape/grape-swagger
+
+## Configuration
+
+Use `Grape.configure` to set up global settings at load time.
+Currently the configurable settings are:
+
+* `param_builder`: Sets the [Parameter Builder](#parameters), defaults to `Grape::Extensions::ActiveSupport::HashWithIndifferentAccess::ParamBuilder`.
+
+To change a setting value make sure that at some point during load time the following code runs
+
+```ruby
+Grape.configure do |config|
+  config.setting = value
+end
+```
+
+For example, for the `param_builder`, the following code could run in an initializer:
+
+```ruby
+Grape.configure do |config|
+  config.param_builder = Grape::Extensions::Hashie::Mash::ParamBuilder
+end
+```
+
+You can also configure a single API:
+
+```ruby
+API.configure do |config|
+  config[key] = value
+end
+```
+
+This will be available inside the API with `configuration`, as if it were
+[mount configuration](#mount-configuration).
 
 ## Parameters
 
@@ -523,13 +788,21 @@ params do
 end
 ```
 
+Or globally with the [Configuration](#configuration) `Grape.configure.param_builder`.
+
 In the example above, `params["color"]` will return `nil` since `params` is a plain `Hash`.
 
 Available parameter builders are `Grape::Extensions::Hash::ParamBuilder`, `Grape::Extensions::ActiveSupport::HashWithIndifferentAccess::ParamBuilder` and `Grape::Extensions::Hashie::Mash::ParamBuilder`.
 
 ### 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.
+  * Perform any parameter renaming on the resulting hash.
+
+Consider the following API endpoint:
 
 ````ruby
 format :json
@@ -562,9 +835,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
 
@@ -592,6 +865,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.
@@ -642,7 +953,7 @@ curl -X GET -H "Content-Type: application/json" localhost:9292/parent/foo/bar
 }
 ````
 
-### Include missing
+### Include Missing
 
 By default `declared(params)` includes parameters that have `nil` values. If you want to return only the parameters that are not `nil`, you can use the `include_missing` option. By default, `include_missing` is set to `true`. Consider the following API:
 
@@ -650,8 +961,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
@@ -682,8 +995,10 @@ curl -X POST -H "Content-Type: application/json" localhost:9292/users/signup -d
 ````json
 {
   "declared_params": {
-    "first_name": "first name",
-    "last_name": null
+    "user": {
+      "first_name": "first name",
+      "last_name": null
+    }
   }
 }
 ````
@@ -804,13 +1119,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']
@@ -867,10 +1182,11 @@ get '/int' integers: { int: '45' }
 ### Custom Types and Coercions
 
 Aside from the default set of supported types listed above, any class can be
-used as a type so long as an explicit coercion method is supplied. If the type
+used as a type as long as an explicit coercion method is supplied. If the type
 implements a class-level `parse` method, Grape will use it automatically.
 This method must take one string argument and return an instance of the correct
-type, or raise an exception to indicate the value was invalid. E.g.,
+type, or return an instance of `Grape::Types::InvalidValue` which optionally
+accepts a message to be returned in the response.
 
 ```ruby
 class Color
@@ -880,15 +1196,16 @@ class Color
   end
 
   def self.parse(value)
-    fail 'Invalid color' unless %w(blue red green).include?(value)
-    new(value)
+    return new(value) if %w[blue red green]).include?(value)
+
+    Grape::Types::InvalidValue.new('Unsupported color')
   end
 end
 
-# ...
-
 params do
   requires :color, type: Color, default: Color.new('blue')
+  requires :more_colors, type: Array[Color] # Collections work
+  optional :unique_colors, type: Set[Color] # Duplicates discarded
 end
 
 get '/stuff' do
@@ -904,7 +1221,7 @@ parameter, and the return value must match the given `type`.
 
 ```ruby
 params do
-  requires :passwd, type: String, coerce_with: Base64.method(:decode)
+  requires :passwd, type: String, coerce_with: Base64.method(:decode64)
   requires :loud_color, type: Color, coerce_with: ->(c) { Color.parse(c.downcase) }
 
   requires :obj, type: Hash, coerce_with: JSON do
@@ -913,6 +1230,7 @@ params do
   end
 end
 ```
+Note that, a `nil` value will call the custom coercion method, while a missing parameter will not.
 
 Example of use of `coerce_with` with a lambda (a class with a `parse` method could also have been used)
 It will parse a string and return an Array of Integers, matching the `Array[Integer]` `type`.
@@ -923,6 +1241,26 @@ params do
 end
 ```
 
+Grape will assert that coerced values match the given `type`, and will reject the request
+if they do not. To override this behaviour, custom types may implement a `parsed?` method
+that should accept a single argument and return `true` if the value passes type validation.
+
+```ruby
+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
+```
+
 ### Multipart File Parameters
 
 Grape makes use of `Rack::Request`'s built-in support for multipart file parameters. Such parameters can be declared with `type: File`:
@@ -933,7 +1271,7 @@ params do
 end
 post '/' do
   params[:avatar][:filename] # => 'avatar.png'
-  params[:avatar][:avatar] # => 'image/png'
+  params[:avatar][:type] # => 'image/png'
   params[:avatar][:tempfile] # => #<File>
 end
 ```
@@ -954,8 +1292,6 @@ get '/' do
   params[:json].inspect
 end
 
-# ...
-
 client.get('/', json: '{"int":1}') # => "{:int=>1}"
 client.get('/', json: '[{"int":"1"}]') # => "[{:int=>1}]"
 
@@ -991,8 +1327,6 @@ get '/' do
   params[:status_code].inspect
 end
 
-# ...
-
 client.get('/', status_code: 'OK_GOOD') # => "OK_GOOD"
 client.get('/', status_code: 300) # => 300
 client.get('/', status_code: %w(404 NOT FOUND)) # => [404, "NOT", "FOUND"]
@@ -1009,15 +1343,13 @@ get '/' do
   params[:status_codes].inspect
 end
 
-# ...
-
 client.get('/', status_codes: %w(1 two)) # => [1, "two"]
 ```
 
 ### Validation of Nested Parameters
 
 Parameters can be nested using `group` or by calling `requires` or `optional` with a block.
-In the above example, this means `params[:media][:url]` is required along with `params[:id]`,
+In the [above example](#parameter-validation-and-coercion), this means `params[:media][:url]` is required along with `params[:id]`,
 and `params[:audio][:format]` is required only if `params[:audio]` is present.
 With a block, `group`, `requires` and `optional` accept an additional option `type` which can
 be either `Array` or `Hash`, and defaults to `Array`. Depending on the value, the nested
@@ -1054,7 +1386,7 @@ end
 
 In the example above Grape will use `blank?` to check whether the `shelf_id` param is present.
 
-Given also takes a `Proc` with custom code. Below, the param `description` is required only if the value of `category` is equal `foo`:
+`given` also takes a `Proc` with custom code. Below, the param `description` is required only if the value of `category` is equal `foo`:
 
 ```ruby
 params do
@@ -1065,6 +1397,18 @@ params do
 end
 ```
 
+You can rename parameters:
+
+```ruby
+params do
+  optional :category, as: :type
+  given type: ->(val) { val == 'foo' } do
+    requires :description
+  end
+end
+```
+
+Note: param in `given` should be the renamed one. In the example, it should be `type`, not `category`.
 
 ### Group Options
 
@@ -1093,6 +1437,23 @@ params do
 end
 ```
 
+### Renaming
+
+You can rename parameters using `as`, which can be useful when refactoring existing APIs:
+
+```ruby
+resource :users do
+  params do
+    requires :email_address, as: :email
+    requires :password
+  end
+  post do
+    User.create!(declared(params)) # User takes email and password
+  end
+end
+```
+
+The value passed to `as` will be the key when calling `params` or `declared(params)`.
 
 ### Built-in Validators
 
@@ -1160,7 +1521,8 @@ end
 
 Alternatively, a Proc with arity one (i.e. taking one argument) can be used to explicitly validate
 each parameter value.  In that case, the Proc is expected to return a truthy value if the parameter
-value is valid.
+value is valid. The parameter will be considered invalid if the Proc returns a falsy value or if it
+raises a StandardError.
 
 ```ruby
 params do
@@ -1170,6 +1532,14 @@ end
 
 While Procs are convenient for single cases, consider using [Custom Validators](#custom-validators) in cases where a validation is used more than once.
 
+Note that [allow_blank](#allow_blank) validator applies while using `:values`. In the following example the absence of `:allow_blank` does not prevent `:state` from receiving blank values because `:allow_blank` defaults to `true`.
+
+```ruby
+params do
+  requires :state, type: Symbol, values: [:active, :inactive]
+end
+```
+
 #### `except_values`
 
 Parameters can be restricted from having a specific set of values with the `:except_values` option.
@@ -1186,6 +1556,17 @@ params do
 end
 ```
 
+#### `same_as`
+
+A `same_as` option can be given to ensure that values of parameters match.
+
+```ruby
+params do
+  requires :password
+  requires :password_confirmation, same_as: :password
+end
+```
+
 #### `regexp`
 
 Parameters can be restricted to match a specific regular expression with the `:regexp` option. If the value
@@ -1245,6 +1626,8 @@ params do
 end
 ```
 
+Note that using `:default` with `mutually_exclusive` will cause multiple parameters to always have a default value and raise a `Grape::Exceptions::Validation` mutually exclusive exception.
+
 #### `at_least_one_of`
 
 Parameters can be defined as 'at_least_one_of', ensuring that at least one parameter gets selected.
@@ -1421,7 +1804,7 @@ params do
 end
 ```
 
-Every validation will have it's own instance of the validator, which means that the validator can have a state.
+Every validation will have its own instance of the validator, which means that the validator can have a state.
 
 ### Validation Errors
 
@@ -1482,6 +1865,8 @@ end
 Grape supports I18n for parameter-related error messages, but will fallback to English if
 translations for the default locale have not been provided. See [en.yml](lib/grape/locale/en.yml) for message keys.
 
+In case your app enforces available locales only and :en is not included in your available locales, Grape cannot fall back to English and will return the translation key for the error message. To avoid this behaviour, either provide a translation for your default locale or add :en to your available locales.
+
 ### Custom Validation messages
 
 Grape supports custom validation messages for parameter-related and coerce-related error messages.
@@ -1493,6 +1878,16 @@ params do
   requires :name, values: { value: 1..10, message: 'not in range from 1 to 10' }, allow_blank: { value: false, message: 'cannot be blank' }, regexp: { value: /^[a-z]+$/, message: 'format is invalid' }, message: 'is required'
 end
 ```
+
+#### `same_as`
+
+```ruby
+params do
+  requires :password
+  requires :password_confirmation, same_as: { value: :password, message: 'not match' }
+end
+```
+
 #### `all_or_none_of`
 
 ```ruby
@@ -1514,6 +1909,7 @@ params do
   mutually_exclusive :beer, :wine, :juice, message: "are mutually exclusive cannot pass both params"
 end
 ```
+
 #### `exactly_one_of`
 
 ```ruby
@@ -1521,9 +1917,10 @@ params do
   optional :beer
   optional :wine
   optional :juice
-  exactly_one_of :beer, :wine, :juice, message: {exactly_one: "are missing, exactly one parameter is required", mutual_exclusion: "are mutually exclusive, exactly one parameter is required"}
+  exactly_one_of :beer, :wine, :juice, message: { exactly_one: "are missing, exactly one parameter is required", mutual_exclusion: "are mutually exclusive, exactly one parameter is required" }
 end
 ```
+
 #### `at_least_one_of`
 
 ```ruby
@@ -1534,13 +1931,15 @@ params do
   at_least_one_of :beer, :wine, :juice, message: "are missing, please specify at least one param"
 end
 ```
+
 #### `Coerce`
 
 ```ruby
 params do
-  requires :int, type: {value: Integer, message: "type cast is invalid" }
+  requires :int, type: { value: Integer, message: "type cast is invalid" }
 end
 ```
+
 #### `With Lambdas`
 
 ```ruby
@@ -1548,6 +1947,7 @@ params do
   requires :name, values: { value: -> { (1..10).to_a }, message: 'not in range from 1 to 10' }
 end
 ```
+
 #### `Pass symbols for i18n translations`
 
 You can pass a symbol if you want i18n translations for your custom validation messages.
@@ -1568,7 +1968,7 @@ en:
         name_required: 'must be present'
 ```
 
-#### `Overriding attribute names`
+#### Overriding Attribute Names
 
 You can also override attribute names.
 
@@ -1586,7 +1986,7 @@ en:
 ```
 Will produce 'Oops! Name must be present'
 
-#### `With Default`
+#### With Default
 
 You cannot set a custom message option for Default as it requires interpolation `%{option1}: %{value1} is incompatible with %{option2}: %{value2}`. You can change the default error message for Default by changing the `incompatible_option_values` message key inside [en.yml](lib/grape/locale/en.yml)
 
@@ -1595,8 +1995,10 @@ params do
   requires :name, values: { value: -> { (1..10).to_a }, message: 'not in range from 1 to 10' }, default: 5
 end
 ```
+
 ## Headers
 
+### Request
 Request headers are available through the `headers` helper or from `env` in their original form.
 
 ```ruby
@@ -1611,13 +2013,30 @@ get do
 end
 ```
 
+#### Header Case Handling
+
+The above example may have been requested as follows:
+
+``` shell
+curl -H "secret_PassWord: swordfish" ...
+```
+
+The header name will have been normalized for you.
+
+- In the `header` helper names will be coerced into a capitalized kebab case.
+- In the `env` collection they appear in all uppercase, in snake case, and prefixed with 'HTTP_'.
+
+The header name will have been normalized per HTTP standards defined in [RFC2616 Section 4.2](https://www.w3.org/Protocols/rfc2616/rfc2616-sec4.html#sec4.2) regardless of what is being sent by a client.
+
+### Response
+
 You can set a response header with `header` inside an API.
 
 ```ruby
 header 'X-Robots-Tag', 'noindex'
 ```
 
-When raising `error!`, pass additional headers as arguments.
+When raising `error!`, pass additional headers as arguments. Additional headers will be merged with headers set before `error!` call.
 
 ```ruby
 error! 'Unauthorized', 401, 'X-Error-Detail' => 'Invalid token.'
@@ -1625,6 +2044,56 @@ error! 'Unauthorized', 401, 'X-Error-Detail' => 'Invalid token.'
 
 ## Routes
 
+To define routes you can use the `route` method or the shorthands for the HTTP verbs. To define a route that accepts any route set to `:any`.
+Parts of the path that are denoted with a colon will be interpreted as route parameters.
+
+```ruby
+route :get, 'status' do
+end
+
+# is the same as
+
+get 'status' do
+end
+
+# is the same as
+
+get :status do
+end
+
+# is NOT the same as
+
+get ':status' do # this makes params[:status] available
+end
+
+# This will make both params[:status_id] and params[:id] available
+
+get 'statuses/:status_id/reviews/:id' do
+end
+```
+
+To declare a namespace that prefixes all routes within, use the `namespace` method. `group`, `resource`, `resources` and `segment` are aliases to this method. Any endpoints within will share their parent context as well as any configuration done in the namespace context.
+
+The `route_param` method is a convenient method for defining a parameter route segment. If you define a type, it will add a validation for this parameter.
+
+```ruby
+route_param :id, type: Integer do
+  get 'status' do
+  end
+end
+
+# is the same as
+
+namespace ':id' do
+  params do
+    requires :id, type: Integer
+  end
+
+  get 'status' do
+  end
+end
+```
+
 Optionally, you can define requirements for your named route parameters using regular
 expressions on namespace or endpoint. The route will match only if all requirements are met.
 
@@ -1745,8 +2214,8 @@ module SharedParams
   extend Grape::API::Helpers
 
   params :order do |options|
-    optional :order_by, type:Symbol, values:options[:order_by], default:options[:default_order_by]
-    optional :order, type:Symbol, values:%i(asc desc), default:options[:default_order]
+    optional :order_by, type: Symbol, values: options[:order_by], default: options[:default_order_by]
+    optional :order, type: Symbol, values: %i(asc desc), default: options[:default_order]
   end
 end
 
@@ -1755,7 +2224,7 @@ class API < Grape::API
 
   desc 'Get a sorted collection.'
   params do
-    use :order, order_by:%i(id created_at), default_order_by: :created_at, default_order: :asc
+    use :order, order_by: %i(id created_at), default_order_by: :created_at, default_order: :asc
   end
 
   get do
@@ -1957,6 +2426,12 @@ instead of a message.
 error!({ error: 'unexpected error', detail: 'missing widget' }, 500)
 ```
 
+You can set additional headers for the response. They will be merged with headers set before `error!` call.
+
+```ruby
+error!('Something went wrong', 500, 'X-Error-Detail' => 'Invalid token.')
+```
+
 You can present documented errors with a Grape entity using the the [grape-entity](https://github.com/ruby-grape/grape-entity) gem.
 
 ```ruby
@@ -2015,7 +2490,7 @@ literally accepts every request.
 
 ## Exception Handling
 
-Grape can be told to rescue all exceptions and return them in the API format.
+Grape can be told to rescue all `StandardError` exceptions and return them in the API format.
 
 ```ruby
 class Twitter::API < Grape::API
@@ -2023,6 +2498,9 @@ class Twitter::API < Grape::API
 end
 ```
 
+This mimics [default `rescue` behaviour](https://ruby-doc.org/core/StandardError.html) when an exception type is not provided.
+Any other exception should be rescued explicitly, see [below](#exceptions-that-should-be-rescued-explicitly).
+
 Grape can also rescue from all exceptions and still use the built-in exception handing.
 This will give the same behavior as `rescue_from :all` with the addition that Grape will use the exception handling defined by all Exception classes that inherit `Grape::Exceptions::Base`.
 
@@ -2062,7 +2540,7 @@ Custom error formatters for existing and additional types can be defined with a
 
 ```ruby
 class Twitter::API < Grape::API
-  error_formatter :txt, ->(message, backtrace, options, env) {
+  error_formatter :txt, ->(message, backtrace, options, env, original_exception) {
     "error: #{message} from #{backtrace}"
   }
 end
@@ -2072,7 +2550,7 @@ You can also use a module or class.
 
 ```ruby
 module CustomFormatter
-  def self.call(message, backtrace, options, env)
+  def self.call(message, backtrace, options, env, original_exception)
     { message: message, backtrace: backtrace }
   end
 end
@@ -2108,7 +2586,7 @@ You can also rescue all exceptions with a code block and handle the Rack respons
 ```ruby
 class Twitter::API < Grape::API
   rescue_from :all do |e|
-    Rack::Response.new([ e.message ], 500, { 'Content-type' => 'text/error' }).finish
+    Rack::Response.new([ e.message ], 500, { 'Content-type' => 'text/error' })
   end
 end
 ```
@@ -2121,8 +2599,8 @@ class Twitter::API < Grape::API
     error!("ArgumentError: #{e.message}")
   end
 
-  rescue_from NotImplementedError do |e|
-    error!("NotImplementedError: #{e.message}")
+  rescue_from NoMethodError do |e|
+    error!("NoMethodError: #{e.message}")
   end
 end
 ```
@@ -2179,9 +2657,9 @@ class Twitter::API < Grape::API
 end
 ```
 
-The `rescue_from` block must return a `Rack::Response` object, call `error!` or re-raise an exception.
+The `rescue_from` handler must return a `Rack::Response` object, call `error!`, or raise an exception (either the original exception or another custom one). The exception raised in `rescue_from` will be handled outside Grape. For example, if you mount Grape in Rails, the exception will be handle by [Rails Action Controller](https://guides.rubyonrails.org/action_controller_overview.html#rescue).
 
-The `with` keyword is available as `rescue_from` options, it can be passed method name or Proc object.
+Alternately, use the `with` option in `rescue_from` to specify a method or a `proc`.
 
 ```ruby
 class Twitter::API < Grape::API
@@ -2197,6 +2675,17 @@ class Twitter::API < Grape::API
 end
 ```
 
+Inside the `rescue_from` block, the environment of the original controller method(`.self` receiver) is accessible through the `#context` method.
+
+```ruby
+class Twitter::API < Grape::API
+  rescue_from :all do |e|
+    user_id = context.params[:user_id]
+    error!("error for #{user_id}")
+  end
+end
+```
+
 #### Rescuing exceptions inside namespaces
 
 You could put `rescue_from` clauses inside a namespace and they will take precedence over ones
@@ -2219,12 +2708,18 @@ class Twitter::API < Grape::API
 end
 ```
 
-Here `'inner'` will be result of handling occured `ArgumentError`.
+Here `'inner'` will be result of handling occurred `ArgumentError`.
 
 #### Unrescuable Exceptions
 
 `Grape::Exceptions::InvalidVersionHeader`, which is raised when the version in the request header doesn't match the currently evaluated version for the endpoint, will _never_ be rescued from a `rescue_from` block (even a `rescue_from :all`) This is because Grape relies on Rack to catch that error and try the next versioned-route for cases where there exist identical Grape endpoints with different versions.
 
+#### Exceptions that should be rescued explicitly
+
+Any exception that is not subclass of `StandardError` should be rescued explicitly.
+Usually it is not a case for an application logic as such errors point to problems in Ruby runtime.
+This is following [standard recommendations for exceptions handling](https://ruby-doc.org/core/Exception.html).
+
 ### Rails 3.x
 
 When mounted inside containers, such as Rails 3.x, errors such as "404 Not Found" or
@@ -2261,7 +2756,6 @@ class API < Grape::API
     end
   end
   post '/statuses' do
-    # ...
     logger.info "#{current_user} has statused"
   end
 end
@@ -2471,6 +2965,9 @@ Built-in formatters are the following.
 * `:serializable_hash`: use object's `serializable_hash` when available, otherwise fallback to `:json`
 * `:binary`: data will be returned "as is"
 
+If a body is present in a request to an API, with a Content-Type header value that is of an unsupported type a
+"415 Unsupported Media Type" error code will be returned by Grape.
+
 Response statuses that indicate no content as defined by [Rack](https://github.com/rack)
 [here](https://github.com/rack/rack/blob/master/lib/rack/utils.rb#L567)
 will bypass serialization and the body entity - though there should be none -
@@ -2742,17 +3239,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
@@ -2762,6 +3261,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
@@ -2773,14 +3292,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
 ```
 
@@ -2811,7 +3329,9 @@ end
 
 ```
 
-Use [warden-oauth2](https://github.com/opperator/warden-oauth2) or [rack-oauth2](https://github.com/nov/rack-oauth2) for OAuth2 support.
+Use [Doorkeeper](https://github.com/doorkeeper-gem/doorkeeper), [warden-oauth2](https://github.com/opperator/warden-oauth2) or [rack-oauth2](https://github.com/nov/rack-oauth2) for OAuth2 support.
+
+You can access the controller params, headers, and helpers through the context with the `#context` method inside any auth middleware inherited from `Grape::Middleware::Auth::Base`.
 
 ## Describing and Inspecting an API
 
@@ -2880,19 +3400,22 @@ class ApiLogger < Grape::Middleware::Base
 end
 ```
 
-## Before and After
+## Before, After and Finally
 
 Blocks can be executed before or after every API call, using `before`, `after`,
 `before_validation` and `after_validation`.
+If the API fails the `after` call will not be triggered, if you need code to execute for sure
+use the `finally`.
 
 Before and after callbacks execute in the following order:
 
 1. `before`
 2. `before_validation`
 3. _validations_
-4. `after_validation`
-5. _the API call_
-6. `after`
+4. `after_validation` (upon successful validation)
+5. _the API call_ (upon successful validation)
+6. `after` (upon successful validation and API call)
+7. `finally` (always)
 
 Steps 4, 5 and 6 only happen if validation succeeds.
 
@@ -2904,9 +3427,7 @@ If a request for a resource is made that triggers the built-in `OPTIONS` handler
 only `before` and `after` callbacks will be executed.  The remaining callbacks will
 be bypassed.
 
-#### Examples
-
-Using a simple `before` block to set a header
+For example, using a simple `before` block to set a header.
 
 ```ruby
 before do
@@ -2914,6 +3435,14 @@ before do
 end
 ```
 
+You can ensure a block of code runs after every request (including failures) with `finally`:
+
+```ruby
+finally do
+  # this code will run after every request (successful or failed)
+end
+```
+
 **Namespaces**
 
 Callbacks apply to each API call within and below the current namespace:
@@ -2942,7 +3471,7 @@ class MyAPI < Grape::API
 end
 ```
 
-The behaviour is then:
+The behavior is then:
 
 ```bash
 GET /           # 'root - '
@@ -2970,7 +3499,7 @@ class MyAPI < Grape::API
 end
 ```
 
-The behaviour is then:
+The behavior is then:
 
 ```bash
 GET /123        # 'Integer'
@@ -3005,7 +3534,7 @@ class Test < Grape::API
 end
 ```
 
-The behaviour is then:
+The behavior is then:
 
 ```bash
 GET /foo/v1       # 'v1-hello'
@@ -3030,7 +3559,7 @@ class MyAPI < Grape::API
 end
 ```
 
-The behaviour is then:
+The behavior is then:
 
 ```bash
 GET /greeting              # {"greeting":"Hello!"}
@@ -3116,11 +3645,21 @@ class API < Grape::API
 end
 ```
 
+You can access the controller params, headers, and helpers through the context with the `#context` method inside any middleware inherited from `Grape::Middleware::Base`.
+
 ### Rails Middleware
 
 Note that when you're using Grape mounted on Rails you don't have to use Rails middleware because it's already included into your middleware stack.
 You only have to implement the helpers to access the specific `env` variable.
 
+If you are using a custom application that is inherited from `Rails::Application` and need to insert a new middleware among the ones initiated via Rails, you will need to register it manually in your custom application class.
+
+```ruby
+class Company::Application < Rails::Application
+  config.middleware.insert_before(Rack::Attack, Middleware::ApiLogger)
+end
+```
+
 ### Remote IP
 
 By default you can access remote IP with `request.ip`. This is the remote IP address implemented by Rack. Sometimes it is desirable to get the remote IP [Rails-style](http://stackoverflow.com/questions/10997005/whats-the-difference-between-request-remote-ip-and-request-ip-in-rails) with `ActionDispatch::RemoteIp`.
@@ -3318,7 +3857,7 @@ describe 'an endpoint that needs helpers stubbed' do
   end
 
   it 'stubs the helper' do
-    # ...
+
   end
 end
 ```
@@ -3355,6 +3894,22 @@ if Rails.env.development?
 end
 ```
 
+For Rails >= 5.1.4, change this:
+
+```ruby
+ActionDispatch::Callbacks.to_prepare do
+  api_reloader.execute_if_updated
+end
+```
+
+to this:
+
+```ruby
+ActiveSupport::Reloader.to_prepare do
+  api_reloader.execute_if_updated
+end
+```
+
 See [StackOverflow #3282655](http://stackoverflow.com/questions/3282655/ruby-on-rails-3-reload-lib-directory-for-each-request/4368838#4368838) for more information.
 
 ## Performance Monitoring
@@ -3391,6 +3946,13 @@ The execution of validators.
 * *validators* - The validators being executed
 * *request* - The request being validated
 
+#### format_response.grape
+
+Serialization or template rendering.
+
+* *env* - The request environment
+* *formatter* - The formatter object (e.g., `Grape::Formatter::Json`)
+
 See the [ActiveSupport::Notifications documentation](http://api.rubyonrails.org/classes/ActiveSupport/Notifications.html) for information on how to subscribe to these events.
 
 ### Monitoring Products
@@ -3401,6 +3963,8 @@ 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)
+* **[Datadog APM](https://docs.datadoghq.com/tracing/)** - [ddtrace](https://github.com/datadog/dd-trace-rb) gem, [documentation](https://docs.datadoghq.com/tracing/setup_overview/setup/ruby/#grape)
 
 ## Contributing to Grape
 
@@ -3409,10 +3973,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-2017 Michael Bleigh, and Intridea, Inc.
+Copyright (c) 2010-2020 Michael Bleigh, Intridea Inc. and Contributors.