Adds .represent method to allow for default entity representations.

Author: Michael Bleigh

lib/grape/api.rb

@@ -43,8 +43,7 @@ def settings_stack
         @settings
       end
 
-      # Set a configuration value for this
-      # namespace.
+      # Set a configuration value for this namespace.
       #
       # @param key [Symbol] The key of the configuration variable.
       # @param value [Object] The value to which to set the configuration variable.
@@ -146,6 +145,31 @@ def rescue_from(*args, &block)
         add(:rescued_errors, args)
       end
 
+      # Allows you to specify a default representation entity for a
+      # class. This allows you to map your models to their respective
+      # entities once and then simply call `present` with the model.
+      #
+      # @example
+      #   class ExampleAPI < Grape::API
+      #     represent User, :with => Entity::User
+      #
+      #     get '/me' do
+      #       present current_user # :with => Entity::User is assumed
+      #     end
+      #   end
+      #
+      # Note that Grape will automatically go up the class ancestry to
+      # try to find a representing entity, so if you, for example, define
+      # an entity to represent `Object` then all presented objects will
+      # bubble up and utilize the entity provided on that `represent` call.
+      #
+      # @param model_class [Class] The model class that will be represented.
+      # @option options [Class] :with The entity class that will represent the model.
+      def represent(model_class, options)
+        raise ArgumentError, "You must specify an entity class in the :with option." unless options[:with] && options[:with].is_a?(Class)
+        add(:representations, model_class => options[:with])
+      end
+
       # Add helper methods that will be accessible from any
       # endpoint within this namespace (and child namespaces).
       #
@@ -352,8 +376,13 @@ def build_endpoint(&block)
 
         befores = aggregate_setting(:befores)
         afters =  aggregate_setting(:afters)
+        representations = settings[:representations] || {}
 
-        endpoint = Grape::Endpoint.generate({:befores => befores, :afters => afters}, &block)
+        endpoint = Grape::Endpoint.generate({
+          :befores => befores, 
+          :afters => afters,
+          :representations => representations
+        }, &block)
         endpoint.send :include, helpers
         b.run endpoint
 

lib/grape/endpoint.rb

@@ -108,6 +108,10 @@ def body(value = nil)
     def present(object, options = {})
       entity_class = options.delete(:with)
 
+      object.class.ancestors.each do |potential|
+        entity_class ||= self.class.options[:representations][potential]
+      end
+
       if entity_class
         embeds = {:env => env}
         embeds[:version] = env['api.version'] if env['api.version']

spec/grape/api_spec.rb

@@ -100,7 +100,18 @@ def app; subject end
     end
 
   end
-  
+
+  describe '.represent' do
+    it 'should require a :with option' do
+      expect{ subject.represent Object, {} }.to raise_error(ArgumentError)
+    end
+
+    it 'should add the association to the :representations setting' do
+      subject.represent Object, :with => BasicObject
+      subject.settings[:representations][Object].should == BasicObject
+    end
+  end
+
   describe '.namespace' do
     it 'should be retrievable and converted to a path' do
       subject.namespace :awesome do

spec/grape/endpoint_spec.rb

@@ -137,6 +137,32 @@ def memoized
       end
       get '/example'
     end
+
+    it 'should pull a representation from the class options if it exists' do
+      entity = Class.new(Grape::Entity)
+      entity.stub!(:represent).and_return("Hiya")
+
+      subject.represent Object, :with => entity
+      subject.get '/example' do
+        present Object.new
+      end
+      get '/example'
+      last_response.body.should == 'Hiya'
+    end
+
+    it 'should pull a representation from the class ancestor if it exists' do
+      entity = Class.new(Grape::Entity)
+      entity.stub!(:represent).and_return("Hiya")
+
+      subclass = Class.new(Object)
+
+      subject.represent Object, :with => entity
+      subject.get '/example' do
+        present subclass.new
+      end
+      get '/example'
+      last_response.body.should == 'Hiya'
+    end
   end
 
   context 'filters' do