Class: Grape::Entity
- Inherits:
-
Object
- Object
- Grape::Entity
- Defined in:
- lib/grape/entity.rb
Overview
An Entity is a lightweight structure that allows you to easily represent data from your application in a consistent and abstracted way in your API. Entities can also provide documentation for the fields exposed.
Entities are not independent structures, rather, they create representations of other Ruby objects using a number of methods that are convenient for use in an API. Once you’ve defined an Entity, you can use it in your API like this:
Instance Attribute Summary collapse
-
#object ⇒ Object
readonly
Returns the value of attribute object.
-
#options ⇒ Object
readonly
Returns the value of attribute options.
Class Method Summary collapse
-
.documentation ⇒ Object
Returns a hash, the keys are symbolized references to fields in the entity, the values are document keys in the entity’s documentation key.
-
.expose(*args, &block) ⇒ Object
This method is the primary means by which you will declare what attributes should be exposed by the entity.
-
.exposures ⇒ Object
Returns a hash of exposures that have been declared for this Entity or ancestors.
-
.format_with(name, &block) ⇒ Object
This allows you to declare a Proc in which exposures can be formatted with.
-
.formatters ⇒ Object
Returns a hash of all formatters that are registered for this and it’s ancestors.
-
.represent(objects, options = {}) ⇒ Object
This convenience method allows you to instantiate one or more entities by passing either a singular or collection of objects.
-
.root(plural, singular = nil) ⇒ Object
This allows you to set a root element name for your representation.
Instance Method Summary collapse
- #documentation ⇒ Object
- #exposures ⇒ Object
- #formatters ⇒ Object
-
#initialize(object, options = {}) ⇒ Entity
constructor
A new instance of Entity.
-
#serializable_hash(runtime_options = {}) ⇒ Object
(also: #as_json)
The serializable hash is the Entity’s primary output.
Constructor Details
#initialize(object, options = {}) ⇒ Entity
Returns a new instance of Entity.
235 236 237 |
# File 'lib/grape/entity.rb', line 235 def initialize(object, = {}) @object, @options = object, end |
Instance Attribute Details
#object ⇒ Object (readonly)
Returns the value of attribute object.
44 45 46 |
# File 'lib/grape/entity.rb', line 44 def object @object end |
#options ⇒ Object (readonly)
Returns the value of attribute options.
44 45 46 |
# File 'lib/grape/entity.rb', line 44 def @options end |
Class Method Details
.documentation ⇒ Object
Returns a hash, the keys are symbolized references to fields in the entity, the values are document keys in the entity’s documentation key. When calling #docmentation, any exposure without a documentation key will be ignored.
104 105 106 107 108 109 110 111 112 113 114 115 116 117 |
# File 'lib/grape/entity.rb', line 104 def self.documentation @documentation ||= exposures.inject({}) do |memo, value| unless value[1][:documentation].nil? || value[1][:documentation].empty? memo[value[0]] = value[1][:documentation] end memo end if superclass.respond_to? :documentation @documentation = superclass.documentation.merge(@documentation) end @documentation end |
.expose(*args, &block) ⇒ Object
This method is the primary means by which you will declare what attributes should be exposed by the entity.
71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 |
# File 'lib/grape/entity.rb', line 71 def self.expose(*args, &block) = args.last.is_a?(Hash) ? args.pop : {} if args.size > 1 raise ArgumentError, "You may not use the :as option on multi-attribute exposures." if [:as] 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 format_with" if block_given? && [:format_with].respond_to?(:call) [:proc] = block if block_given? args.each do |attribute| exposures[attribute.to_sym] = end end |
.exposures ⇒ Object
Returns a hash of exposures 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.
91 92 93 94 95 96 97 98 99 |
# File 'lib/grape/entity.rb', line 91 def self.exposures @exposures ||= {} if superclass.respond_to? :exposures @exposures = superclass.exposures.merge(@exposures) end @exposures end |
.format_with(name, &block) ⇒ Object
This allows you to declare a Proc in which exposures can be formatted with. It take a block with an arity of 1 which is passed as the value of the exposed attribute.
147 148 149 150 |
# File 'lib/grape/entity.rb', line 147 def self.format_with(name, &block) raise ArgumentError, "You must pass a block for formatters" unless block_given? formatters[name.to_sym] = block end |
.formatters ⇒ Object
Returns a hash of all formatters that are registered for this and it’s ancestors.
153 154 155 156 157 158 159 160 161 |
# File 'lib/grape/entity.rb', line 153 def self.formatters @formatters ||= {} if superclass.respond_to? :formatters @formatters = superclass.formatters.merge(@formatters) end @formatters end |
.represent(objects, options = {}) ⇒ Object
This convenience method allows you to instantiate one or more entities by passing either a singular or collection of objects. Each object will be initialized with the same options. If an array of objects is passed in, an array of entities will be returned. If a single object is passed in, a single entity will be returned.
entity. Pass nil or false to represent the object or objects with no
root name even if one is defined for the entity.
220 221 222 223 224 225 226 227 228 229 230 231 232 233 |
# File 'lib/grape/entity.rb', line 220 def self.represent(objects, = {}) inner = if objects.respond_to?(:to_ary) objects.to_ary().map{|o| self.new(o, {:collection => true}.merge())} else self.new(objects, ) end root_element = if .has_key?(:root) [:root] else objects.respond_to?(:to_ary) ? @collection_root : @root end root_element ? { root_element => inner } : inner end |
.root(plural, singular = nil) ⇒ Object
This allows you to set a root element name for your representation.
202 203 204 205 |
# File 'lib/grape/entity.rb', line 202 def self.root(plural, singular=nil) @collection_root = plural @root = singular end |
Instance Method Details
#documentation ⇒ Object
243 244 245 |
# File 'lib/grape/entity.rb', line 243 def documentation self.class.documentation end |
#exposures ⇒ Object
239 240 241 |
# File 'lib/grape/entity.rb', line 239 def exposures self.class.exposures end |
#formatters ⇒ Object
247 248 249 |
# File 'lib/grape/entity.rb', line 247 def formatters self.class.formatters end |
#serializable_hash(runtime_options = {}) ⇒ Object Also known as: as_json
The serializable hash is the Entity’s primary output. It is the transformed hash for the given data model and is used as the basis for serialization to JSON and other formats.
258 259 260 261 262 263 264 265 |
# File 'lib/grape/entity.rb', line 258 def serializable_hash( = {}) return nil if object.nil? opts = .merge( || {}) exposures.inject({}) do |output, (attribute, )| output[key_for(attribute)] = value_for(attribute, opts) if conditions_met?(, opts) output end end |