Added documentation to entities

[flah00]

Entities and documentation seem like a logical unit. Combining inheritable exposures with inheritable docs would be magical! I am currently forced to define a hash (object_fields) in a call to desc and maintain an entity and documentation separately.

My current work flow

1. Create an entity
2. Create an endpoint
3. Write a desc for the endpoint

    class Api::Entities::Widget < Grape::Entity
        expose :slug, :name
    end
...
    desc "blah blah", { 
        :params => { 
            :slug => { :type => "string", :desc => "unique id" }
        },
        :object_fields => {
            :slug => { :type => "string", :desc => "unique id" },
            :name => { :type => "string", :desc => "the name of the object" }
        }
    }

Inevitably, our very immature API requires field fiddling and I have to revisit the entity. Suddenly I'm faced with the very frustrating prospect of changing the desc and the entity ... and I don't always remember. When I add something to the entity, I need to remember to add it to the object_fields hash as well.

If entities become aware of one more key, maybe called documentation, I could gain immediate visibility into which fields are and aren't documented... and I'd be happier.

Consequently, I'd now be able to easily include my documentation in my desc block

    class Api::Entities::Widget < Grape::Entity
        expose :slug, :documentation => { :type => "string", :desc => "unique id" }
        expose :name, :documentation => { :type => "string", :desc => "the name of the object" }
    end
...
    desc "blah blah", { 
        :params => { 
            :slug => { :type => "string", :desc => "unique id" }
        },
        :object_fields => Api::Entities::Widget.documentation
    } 

[dblock]

I like this very much. I'm going to let it hang a bit to see if other people would like to comment, in the meantime, could you spend a moment updating changelog and readme around the documentation area? Maybe a section inside "Describing and Inspecting the API" on entities?

[flah00]

Cool! I'll update the readme shortly.

[dblock]

Very nice, merging. Thx.