Errors can now be presented with a Grape::Entity class.

Author: Dieter Späth

CHANGELOG.md

@@ -10,6 +10,7 @@
 * [#703](https://github.com/intridea/grape/pull/703): Removed `Grape::Middleware::Auth::OAuth2` - [@dspaeth-faber](https://github.com/dspaeth-faber).
 * [#719](https://github.com/intridea/grape/pull/719): Allow passing options hash to a custom validator - [@elado](https://github.com/elado).
 * [#716](https://github.com/intridea/grape/pull/716): Calling `content-type` will now return the current content-type - [@dblock](https://github.com/dblock).
+* [#705](https://github.com/intridea/grape/pull/705): Errors can now be presented with a `Grape::Entity` class - [@dspaeth-faber](https://github.com/dspaeth-faber).
 * Your contribution here.
 
 0.8.0 (7/10/2014)

README.md

@@ -310,10 +310,10 @@ You can use `status` to query and set the actual HTTP Status Code
 ```ruby
 post do
   status 202
-  
+
   if status == 200
      # do some thing
-  end 
+  end
 end
 ```
 
@@ -944,6 +944,31 @@ instead of a message.
 error!({ error: "unexpected error", detail: "missing widget" }, 500)
 ```
 
+You can present documented errors with a Grape entity using the the [grape-entity](https://github.com/intridea/grape-entity) gem.
+
+```ruby
+module API
+  class Error < Grape::Entity
+    expose :code
+    expose :message
+  end
+end
+```
+
+The following example specifies the entity to use in the `http_codes` definition.
+
+```
+desc 'My Route', http_codes: [[408, 'Unauthorized', API::Error]]
+error!({ message: 'Unauthorized' }, 408)
+```
+
+The following example specifies the presented entity explicitly in the error message.
+
+```ruby
+desc 'My Route', http_codes: [[408, 'Unauthorized']]
+error!({ message: 'Unauthorized', with: API::Error }, 408)
+```
+
 ### Default Error HTTP Status Code
 
 By default Grape returns a 500 status code from `error!`. You can change this with `default_error_status`.
@@ -1468,8 +1493,8 @@ formatter.
 
 ### Basic and Digest Auth
 
-Grape has built-in Basic and Digest authentication (the given `block` 
-is executed in the context of the current `Endpoint`).  Authentication 
+Grape has built-in Basic and Digest authentication (the given `block`
+is executed in the context of the current `Endpoint`).  Authentication
 applies to the current namespace and any children, but not parents.
 
 ```ruby
@@ -1496,7 +1521,7 @@ For registering a Middlewar you need the following options:
 
 * `label` - the name for your authenticator to use it later
 * `MiddlewareClass` - the MiddlewareClass to use for authentication
-* `option_lookup_proc` - A Proc with one Argument to lookup the options at 
+* `option_lookup_proc` - A Proc with one Argument to lookup the options at
 runtime (return value is an `Array` as Paramter for the Middleware).
 
 Example:

grape.gemspec

@@ -24,7 +24,7 @@ Gem::Specification.new do |s|
   s.add_runtime_dependency 'virtus', '>= 1.0.0'
   s.add_runtime_dependency 'builder'
 
-  s.add_development_dependency 'grape-entity', '>= 0.2.0'
+  s.add_development_dependency 'grape-entity', '>= 0.4.4'
   s.add_development_dependency 'rake'
   s.add_development_dependency 'maruku'
   s.add_development_dependency 'yard'

lib/grape/dsl/inside_route.rb

@@ -173,22 +173,7 @@ def present(*args)
                       else
                         [nil, args.first]
                       end
-        entity_class = options.delete(:with)
-
-        if entity_class.nil?
-          # entity class not explicitely defined, auto-detect from relation#klass or first object in the collection
-          object_class = if object.respond_to?(:klass)
-                           object.klass
-                         else
-                           object.respond_to?(:first) ? object.first.class : object.class
-                         end
-
-          object_class.ancestors.each do |potential|
-            entity_class ||= (settings[:representations] || {})[potential]
-          end
-
-          entity_class ||= object_class.const_get(:Entity) if object_class.const_defined?(:Entity) && object_class.const_get(:Entity).respond_to?(:represent)
-        end
+        entity_class = entity_class_for_obj(object, options)
 
         root = options.delete(:root)
 
@@ -216,6 +201,27 @@ def present(*args)
       def route
         env["rack.routing_args"][:route_info]
       end
+
+      def entity_class_for_obj(object, options)
+        entity_class = options.delete(:with)
+
+        if entity_class.nil?
+          # entity class not explicitely defined, auto-detect from relation#klass or first object in the collection
+          object_class = if object.respond_to?(:klass)
+                           object.klass
+                         else
+                           object.respond_to?(:first) ? object.first.class : object.class
+                         end
+
+          object_class.ancestors.each do |potential|
+            entity_class ||= (settings[:representations] || {})[potential]
+          end
+
+          entity_class ||= object_class.const_get(:Entity) if object_class.const_defined?(:Entity) && object_class.const_get(:Entity).respond_to?(:represent)
+        end
+
+        entity_class
+      end
     end
   end
 end

lib/grape/error_formatter/base.rb

@@ -26,6 +26,34 @@ def formatter_for(api_format, options = {})
           end
         end
       end
+
+      module_function
+
+      def present(message, env)
+        present_options = {}
+        present_options[:with] = message.delete(:with) if message.is_a?(Hash)
+
+        presenter = env['api.endpoint'].entity_class_for_obj(message, present_options)
+
+        unless presenter || env['rack.routing_args'].nil?
+          # env['api.endpoint'].route does not work when the error occurs within a middleware
+          # the Endpoint does not have a valid env at this moment
+          http_codes = env['rack.routing_args'][:route_info].route_http_codes || []
+          found_code = http_codes.find do |http_code|
+            (http_code[0].to_i == env['api.endpoint'].status) && http_code[2].respond_to?(:represent)
+          end
+
+          presenter = found_code[2] if found_code
+        end
+
+        if presenter
+          embeds = { env: env }
+          embeds[:version] = env['api.version'] if env['api.version']
+          message = presenter.represent(message, embeds).serializable_hash
+        end
+
+        message
+      end
     end
   end
 end

lib/grape/error_formatter/json.rb

@@ -3,6 +3,8 @@ module ErrorFormatter
     module Json
       class << self
         def call(message, backtrace, options = {}, env = nil)
+          message = Grape::ErrorFormatter::Base.present(message, env)
+
           result = message.is_a?(Hash) ? message : { error: message }
           if (options[:rescue_options] || {})[:backtrace] && backtrace && !backtrace.empty?
             result = result.merge(backtrace: backtrace)

lib/grape/error_formatter/txt.rb

@@ -3,6 +3,8 @@ module ErrorFormatter
     module Txt
       class << self
         def call(message, backtrace, options = {}, env = nil)
+          message = Grape::ErrorFormatter::Base.present(message, env)
+
           result = message.is_a?(Hash) ? MultiJson.dump(message) : message
           if (options[:rescue_options] || {})[:backtrace] && backtrace && !backtrace.empty?
             result += "\r\n "

lib/grape/error_formatter/xml.rb

@@ -3,6 +3,8 @@ module ErrorFormatter
     module Xml
       class << self
         def call(message, backtrace, options = {}, env = nil)
+          message = Grape::ErrorFormatter::Base.present(message, env)
+
           result = message.is_a?(Hash) ? message : { message: message }
           if (options[:rescue_options] || {})[:backtrace] && backtrace && !backtrace.empty?
             result = result.merge(backtrace: backtrace)

spec/grape/api_spec.rb

@@ -1,5 +1,6 @@
 require 'spec_helper'
 require 'shared/versioning_examples'
+require 'grape-entity'
 
 describe Grape::API do
   subject { Class.new(Grape::API) }
@@ -1762,6 +1763,44 @@ def self.call(object, env)
     end
   end
 
+  context 'http_codes' do
+    let(:error_presenter) do
+      Class.new(Grape::Entity) do
+        expose :code
+        expose :static
+
+        def static
+          'some static text'
+        end
+      end
+    end
+
+    it 'is used as presenter' do
+      subject.desc 'some desc', http_codes: [
+        [408, 'Unauthorized', error_presenter]
+      ]
+
+      subject.get '/exception' do
+        error!({ code: 408 }, 408)
+      end
+
+      get '/exception'
+      expect(last_response.status).to eql 408
+      expect(last_response.body).to eql({ code: 408, static: 'some static text' }.to_json)
+    end
+
+    it 'presented with' do
+      error = { code: 408, with: error_presenter }
+      subject.get '/exception' do
+        error! error, 408
+      end
+
+      get '/exception'
+      expect(last_response.status).to eql 408
+      expect(last_response.body).to eql({ code: 408, static: 'some static text' }.to_json)
+    end
+  end
+
   context 'routes' do
     describe 'empty api structure' do
       it 'returns an empty array of routes' do

spec/grape/middleware/error_spec.rb

@@ -1,6 +1,17 @@
 require 'spec_helper'
+require 'grape-entity'
 
 describe Grape::Middleware::Error do
+  module ErrorSpec
+    class ErrorEntity < Grape::Entity
+      expose :code
+      expose :static
+
+      def static
+        'static text'
+      end
+    end
+  end
   class ErrApp
     class << self
       attr_accessor :error
@@ -13,12 +24,16 @@ def call(env)
   end
 
   def app
+    opts = options
     Rack::Builder.app do
-      use Grape::Middleware::Error, default_message: 'Aww, hamburgers.'
+      use Spec::Support::EndpointFaker
+      use Grape::Middleware::Error, opts
       run ErrApp
     end
   end
 
+  let(:options) {  { default_message: 'Aww, hamburgers.' } }
+
   it 'sets the status code appropriately' do
     ErrApp.error = { status: 410 }
     get '/'
@@ -42,4 +57,21 @@ def app
     get '/'
     expect(last_response.body).to eq('Aww, hamburgers.')
   end
+
+  context 'with http code' do
+    let(:options) {  { default_message: 'Aww, hamburgers.' } }
+    it 'adds the status code if wanted' do
+      ErrApp.error = { message: { code: 200 } }
+      get '/'
+
+      expect(last_response.body).to eq({ code: 200 }.to_json)
+    end
+
+    it 'presents an error message' do
+      ErrApp.error = { message: { code: 200, with: ErrorSpec::ErrorEntity } }
+      get '/'
+
+      expect(last_response.body).to eq({ code: 200, static: 'static text' }.to_json)
+    end
+  end
 end