Class: Brainstem::ApiDocs::Endpoint

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Includes:
Concerns::Formattable, Concerns::Optional
Defined in:
lib/brainstem/api_docs/endpoint.rb

Constant Summary collapse

ACTION_ORDER = 
%w(index show create update delete)

Instance Attribute Summary collapse

Attributes included from Concerns::Formattable

#formatters

Instance Method Summary collapse

Methods included from Concerns::Formattable

#formatted_as, #formatter_type

Constructor Details

#initialize(atlas, options = {}) {|_self| ... } ⇒ Endpoint

Returns a new instance of Endpoint.

Yields:

  • (_self)

Yield Parameters:



31
32
33
34
35
 
# File 'lib/brainstem/api_docs/endpoint.rb', line 31

def initialize(atlas, options = {})
  self.atlas = atlas
  super options
  yield self if block_given?
end

Instance Attribute Details

#action ⇒ Object

Returns the value of attribute action.



38
39
40
 
# File 'lib/brainstem/api_docs/endpoint.rb', line 38

def action
  @action
end

#atlas ⇒ Object

Returns the value of attribute atlas.



38
39
40
 
# File 'lib/brainstem/api_docs/endpoint.rb', line 38

def atlas
  @atlas
end

#controller ⇒ Object

Returns the value of attribute controller.



38
39
40
 
# File 'lib/brainstem/api_docs/endpoint.rb', line 38

def controller
  @controller
end

#controller_name ⇒ Object

Returns the value of attribute controller_name.



38
39
40
 
# File 'lib/brainstem/api_docs/endpoint.rb', line 38

def controller_name
  @controller_name
end

#http_methods ⇒ Object

Returns the value of attribute http_methods.



38
39
40
 
# File 'lib/brainstem/api_docs/endpoint.rb', line 38

def http_methods
  @http_methods
end

#path ⇒ Object

Returns the value of attribute path.



38
39
40
 
# File 'lib/brainstem/api_docs/endpoint.rb', line 38

def path
  @path
end

#presenter ⇒ Object

Stores the ApiDocs::Presenter object associated with this endpoint.



170
171
172
 
# File 'lib/brainstem/api_docs/endpoint.rb', line 170

def presenter
  @presenter
end

Instance Method Details

#<=>(other) ⇒ Object

Sorts this endpoint in comparison to other endpoints.

Follows a manually defined order of precedence (ACTION_ORDER). The earlier an action name appears on the list, the earlier it is sorted.

In the event that an action is not on the list, it is sorted after any listed routes, and then sorted alphabetically among the remainder.



71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
 
# File 'lib/brainstem/api_docs/endpoint.rb', line 71

def <=>(other)

  # Any unordered routes are assigned an index of +ACTION_ORDER.count+.
  ordered_actions_count = ACTION_ORDER.count
  own_action_priority     = ACTION_ORDER.index(action.to_s)       || ordered_actions_count
  other_action_priority   = ACTION_ORDER.index(other.action.to_s) || ordered_actions_count

  # If the priorities are unequal (i.e. one or both are named; duplicates
  # should not exist for named routes):
  if own_action_priority != other_action_priority

    # Flip order if this action's priority is greater than the other.
    # other_action_priority <=> own_action_priority
    own_action_priority <=> other_action_priority

  # If the priorities are equal, i.e. both not in the list:
  else

    # Flip order if this action's name is alphabetically later.
    action.to_s <=> other.action.to_s
  end
end

#action_configuration ⇒ Object

Helper for retrieving action-specific configuration from the controller.



187
188
189
 
# File 'lib/brainstem/api_docs/endpoint.rb', line 187

def action_configuration
  configuration[action] || {}
end

#contextual_documentation(key) ⇒ Object

Returns a key if it exists and is documentable



203
204
205
206
207
 
# File 'lib/brainstem/api_docs/endpoint.rb', line 203

def contextual_documentation(key)
  action_configuration.has_key?(key) &&
    !action_configuration[key][:nodoc] &&
    action_configuration[key][:info]
end

#declared_presented_class ⇒ Object

Used to retrieve this endpoint’s presenter constant.



160
161
162
163
164
 
# File 'lib/brainstem/api_docs/endpoint.rb', line 160

def declared_presented_class
  valid_presents.has_key?(:target_class) &&
    !valid_presents[:nodoc] &&
    valid_presents[:target_class]
end

#default_configuration ⇒ Object

Retrieves default action context from the controller.



195
196
197
 
# File 'lib/brainstem/api_docs/endpoint.rb', line 195

def default_configuration
  configuration[:_default] || {}
end

#description ⇒ Object 



112
113
114
 
# File 'lib/brainstem/api_docs/endpoint.rb', line 112

def description
  @description ||= contextual_documentation(:description) || ""
end

#key_with_default_fallback(key) ⇒ Object 



210
211
212
 
# File 'lib/brainstem/api_docs/endpoint.rb', line 210

def key_with_default_fallback(key)
  action_configuration[key] || default_configuration[key]
end

#merge_http_methods!(methods) ⇒ Object

Merges http methods (for de-duping Rails’ routes).



57
58
59
 
# File 'lib/brainstem/api_docs/endpoint.rb', line 57

def merge_http_methods!(methods)
  self.http_methods |= methods
end

#nodoc? ⇒ Boolean

Is the entire endpoint undocumentable?

Returns:

  • (Boolean) 


102
103
104
 
# File 'lib/brainstem/api_docs/endpoint.rb', line 102

def nodoc?
  action_configuration[:nodoc]
end

#presenter_title ⇒ Object 



215
216
217
 
# File 'lib/brainstem/api_docs/endpoint.rb', line 215

def presenter_title
  presenter && presenter.title
end

#relative_presenter_path_from_controller(format) ⇒ Object

Returns the relative path from this endpoint’s controller to this endpoint’s declared presenter.



224
225
226
227
228
229
230
231
 
# File 'lib/brainstem/api_docs/endpoint.rb', line 224

def relative_presenter_path_from_controller(format)
  if presenter && controller
    controller_path = Pathname.new(File.dirname(controller.suggested_filename_link(format)))
    presenter_path  = Pathname.new(presenter.suggested_filename_link(format))

    presenter_path.relative_path_from(controller_path).to_s
  end
end

#root_param_keys ⇒ Hash{Symbol => Array,NilClass}

Returns a hash of all root-level params with values of an array of the parameters nested underneath, or nil in the event they are root-level non-nested params.

Returns:

  • (Hash{Symbol => Array,NilClass}) —

    root keys and the keys nested under them, or nil if not a nested param.



130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
 
# File 'lib/brainstem/api_docs/endpoint.rb', line 130

def root_param_keys
  @root_param_keys ||= begin
    valid_params.to_h
      .inject({}) do |hsh, (field_name, data)|
        next hsh if data[:nodoc]

        if data.has_key?(:root)
          key  = data[:root].respond_to?(:call) ? data[:root].call(controller.const) : data[:root]
          (hsh[key] ||= []) << field_name
        else
          hsh[field_name] = nil
        end

        hsh
      end
  end
end

#title ⇒ Object 



107
108
109
 
# File 'lib/brainstem/api_docs/endpoint.rb', line 107

def title
  @title ||= contextual_documentation(:title) || action.to_s.humanize
end

#to_s ⇒ Object

Pretty prints each endpoint.



49
50
51
 
# File 'lib/brainstem/api_docs/endpoint.rb', line 49

def to_s
  "#{http_methods.join(" / ")} #{path}"
end

#valid_options ⇒ Object 



19
20
21
22
23
24
25
26
27
28
 
# File 'lib/brainstem/api_docs/endpoint.rb', line 19

def valid_options
  super | [
    :path,
    :http_methods,
    :controller,
    :controller_name,
    :action,
    :presenter
  ]
end

#valid_params ⇒ Object 



117
118
119
 
# File 'lib/brainstem/api_docs/endpoint.rb', line 117

def valid_params
  @valid_params ||= key_with_default_fallback(:valid_params)
end

#valid_presents ⇒ Object

Retrieves the presents settings.



152
153
154
 
# File 'lib/brainstem/api_docs/endpoint.rb', line 152

def valid_presents
  key_with_default_fallback(:presents) || {}
end