updated documentation for entities

Author: Philip Champon

README.markdown

@@ -443,11 +443,89 @@ RSpec.configure do |config|
 end
 ```
 
+## Reusable Responses with Entities
+
+Entities are a simple and reusable means for converting Ruby objects to API responses.
+Entities can be used to conditionally include fields, nest other entities, and build
+ever larger responses, using inheritance.
+
+### Defining Entities
+
+Entities inherit from Grape::Entity, and define a simple DSL. The `#expose` method can be called in 
+a number of ways. When processing options passed to exposures two keys will always be defined, :version
+and :collection. The :version key is define as api.version. The :collection key is boolean, and defined
+as true if the object presented is an array.
+
+  * expose SYMBOLS
+    * define a list of fields which will always be exposed
+  * expose SYMBOLS, HASH
+    * HASH keys include :if, :unless, :proc, :as, :using, :format_with, :documentation
+      * :if and :unless accept hashes (passed during runtime) or procs (arguments are object and options)
+  * expose SYMBOL, {:format_with => :formatter}
+    * expose a value, formatting it first
+    * `:format_with` can only be applied to one exposure at a time
+  * expose SYMBOL, {:as => "alias"}
+    * Expose a value, changing its hash key from SYMBOL to alias
+    * `:as` can only be applied to one exposure at a time
+  * expose SYMBOL BLOCK
+    * block arguments are object and options
+    * expose the value returned by the block
+    * `block` can only be applied to one exposure at a time
+
+``` ruby
+module API
+  module Entities
+    class User < Grape::Entity
+      expose :first_name, :last_name
+      expose :field, :documentation => {:type => "string", :desc => "words go here"}
+      expose :email, :if => {:type => :full}
+      expose :user_type, user_id, :if => lambda{|user,options| user.confirmed?}
+      expose(:name){|user,options| [user.first_name, user.last_name].join(' ')}
+      expose :latest_status, :using => API::Status, :as => :status
+    end
+  end
+end
+
+module API
+  module Entities
+    class UserDetailed < API::Entities::User
+      expose :account_id
+    end
+  end
+end
+```
+
+### Using Entities
+
+Once an entity is defined, it can be used within endpoints, by calling #present. The #present
+method accepts two arguments, the object to be presented and the options associated with it. The
+options hash must always include :with, which defines the entity to expose.
+
+If the entity includes documentation it can be included in an endpoint's description.
+
+``` ruby
+module API
+  class Users < Grape::API
+    version 'v1'
+
+    desc 'User index', {
+      :object_fields => API::Entities::User.documentation
+    }
+    get '/users' do
+      @users = User.all
+      type = current_user.admin? ? :full : :default
+      present @users, with: API::Entities::User, :type => type
+    end
+  end
+end
+```
+
 ## Describing and Inspecting an API
 
 Grape lets you add a description to an API along with any other optional
 elements that can also be inspected at runtime.
-This can be useful for generating documentation.
+This can be useful for generating documentation. If the response 
+requires documentation, consider using an entity.
 
 ``` ruby
 class TwitterAPI < Grape::API

lib/grape/entity.rb

@@ -63,6 +63,11 @@ class Entity
     #   will be called with the represented object as well as the
     #   runtime options that were passed in. You can also just supply a
     #   block to the expose call to achieve the same effect.
+    # @option options :documentation Provide documenation for an exposed 
+    #   field, typically the value is a hash with two fields, type and desc. 
+    #   Call the class or instance method #documentation for use with #desc. 
+    #   When calling #docmentation, any exposure without a documentation key 
+    #   will be ignored.
     def self.expose(*args, &block)
       options = args.last.is_a?(Hash) ? args.pop : {}
 
@@ -71,7 +76,7 @@ def self.expose(*args, &block)
         raise ArgumentError, "You may not use block-setting on multi-attribute exposures." if block_given?
       end
 
-      raise ArgumentError, "You may not use block-setting when also using " if block_given? && options[:format_with].respond_to?(:call)
+      raise ArgumentError, "You may not use block-setting when also using format_with" if block_given? && options[:format_with].respond_to?(:call)
 
       options[:proc] = block if block_given?
 
@@ -94,8 +99,8 @@ def self.exposures
     end
 
     # Returns a hash of documentation hashes that have been declared for this Entity or ancestors. The keys
-    # are symbolized references to methods on the containing object, the values are
-    # the options that were passed into expose.
+    # are symbolized references to fields in the response, the values are those defined in the 
+    # Entity's documentation key.
     def self.documentation
       @documentation ||= exposures.inject({}) do |memo, value|
                            unless value[1][:documentation].nil? || value[1][:documentation].empty?
@@ -140,7 +145,7 @@ def self.documentation
     #   end
     #
     def self.format_with(name, &block)
-      raise ArgumentError, "You must has a block for formatters" unless block_given?
+      raise ArgumentError, "You must pass a block for formatters" unless block_given?
       formatters[name.to_sym] = block
     end