Allow entity root key to be overridden

When calling represent, pass the :root => 'name'
option to use 'name' as the root key. Pass
:root => nil (or false) to represent with no root
key.

Author: Jon Evans

lib/grape/entity.rb

@@ -138,14 +138,22 @@ def self.root(plural, singular=nil)
     # @param objects [Object or Array] One or more objects to be represented.
     # @param options [Hash] Options that will be passed through to each entity
     #   representation.
+    #
+    # @option options :root [String] override the default root name set for the
+    #   entity. Pass nil or false to represent the object or objects with no
+    #   root name even if one is defined for the entity.
     def self.represent(objects, options = {})
       inner = if objects.is_a?(Array)
         objects.map{|o| self.new(o, {:collection => true}.merge(options))}
       else
         self.new(objects, options)
       end
 
-      root_element = objects.is_a?(Array) ? @collection_root : @root
+      root_element = if options.has_key?(:root)
+        options[:root]
+      else
+        objects.is_a?(Array) ? @collection_root : @root
+      end
       root_element ? { root_element => inner } : inner
     end
 

spec/grape/entity_spec.rb

@@ -84,6 +84,23 @@
             representation['things'].reject{|r| r.kind_of?(subject)}.should be_empty
           end
         end
+
+        context 'it can be overridden' do
+          it 'can be disabled' do
+            representation = subject.represent(4.times.map{Object.new}, :root=>false)
+            representation.should be_kind_of(Array)
+            representation.size.should == 4
+            representation.reject{|r| r.kind_of?(subject)}.should be_empty
+          end
+          it 'can use a different name' do
+            representation = subject.represent(4.times.map{Object.new}, :root=>'others')
+            representation.should be_kind_of(Hash)
+            representation.should have_key('others')
+            representation['others'].should be_kind_of(Array)
+            representation['others'].size.should == 4
+            representation['others'].reject{|r| r.kind_of?(subject)}.should be_empty
+          end
+        end
       end
 
       context 'with singular root key' do