Adds documentation and specs for callback response behaviors

Author: arempe93

README.md

@@ -2453,15 +2453,19 @@ Before and after callbacks execute in the following order:
 
 Steps 4, 5 and 6 only happen if validation succeeds.
 
-E.g. using `before`:
+#### Examples
+
+Using a simple `before` block to set a header
 
 ```ruby
 before do
   header 'X-Robots-Tag', 'noindex'
 end
 ```
 
-The block applies to every API call within and below the current namespace:
+**Namespaces**
+
+Callbacks apply to each API call within and below the current namespace:
 
 ```ruby
 class MyAPI < Grape::API
@@ -2495,8 +2499,7 @@ GET /foo        # 'root - foo - blah'
 GET /foo/bar    # 'root - foo - bar - blah'
 ```
 
-Params on a `namespace` (or whatever alias you are using) also work when using
-`before_validation` or `after_validation`:
+Params on a `namespace` (or whichever alias you are using) will also be available when using `before_validation` or `after_validation`:
 
 ```ruby
 class MyAPI < Grape::API
@@ -2523,6 +2526,8 @@ GET /123        # 'Fixnum'
 GET /foo        # 400 error - 'blah is invalid'
 ```
 
+**Versioning**
+
 When a callback is defined within a version block, it's only called for the routes defined in that block.
 
 ```ruby
@@ -2556,6 +2561,33 @@ GET /foo/v1       # 'v1-hello'
 GET /foo/v2       # 'v2-hello'
 ```
 
+**Altering Responses**
+
+Using `present` in any callback allows you to add data to a response:
+
+```ruby
+class MyAPI < Grape::API
+  format :json
+
+  after_validation do
+    present :name, params[:name] if params[:name]
+  end
+
+  get '/greeting' do
+    present :greeting, 'Hello!'
+  end
+end
+```
+
+The behaviour is then:
+
+```bash
+GET /greeting              # {"greeting":"Hello!"}
+GET /greeting?name=Alan    # {"name":"Alan","greeting":"Hello!"}
+```
+
+Instead of altering a response, you can also terminate and rewrite it from any callback using `error!`, including `after`. This will cause all subsequent steps in the process to not be called. **This includes the actual api call and any callbacks**
+
 ## Anchoring
 
 Grape by default anchors all request paths, which means that the request URL

spec/grape/endpoint_spec.rb

@@ -887,6 +887,57 @@ def memoized
         expect(last_response.body).to eq('body')
       end
     end
+
+    it 'allows adding to response with present' do
+      subject.format :json
+      subject.before { present :before, 'before' }
+      subject.before_validation { present :before_validation, 'before_validation' }
+      subject.after_validation { present :after_validation, 'after_validation' }
+      subject.after { present :after, 'after' }
+      subject.get :all_filters do
+        present :endpoint, 'endpoint'
+      end
+
+      get '/all_filters'
+      json = JSON.parse(last_response.body)
+      expect(json.keys).to match_array %w(before before_validation after_validation endpoint after)
+    end
+
+    context 'when terminating the response with error!' do
+      it 'breaks normal call chain' do
+        called = []
+        subject.before { called << 'before' }
+        subject.before_validation { called << 'before_validation' }
+        subject.after_validation { error! :oops, 500 }
+        subject.after { called << 'after' }
+        subject.get :error_filters do
+          called << 'endpoint'
+          ''
+        end
+
+        get '/error_filters'
+        expect(last_response.status).to eql 500
+        expect(called).to match_array %w(before before_validation)
+      end
+
+      it 'allows prior and parent filters of same type to run' do
+        called = []
+        subject.before { called << 'parent' }
+        subject.namespace :parent do
+          before { called << 'prior' }
+          before { error! :oops, 500 }
+          before { called << 'subsequent' }
+          get :hello do
+            called << :endpoint
+            'Hello!'
+          end
+        end
+
+        get '/parent/hello'
+        expect(last_response.status).to eql 500
+        expect(called).to match_array %w(parent prior)
+      end
+    end
   end
 
   context 'anchoring' do