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.



192
193
194
 
# File 'lib/brainstem/api_docs/endpoint.rb', line 192

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.



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

def action_configuration
  configuration[action] || {}
end

#contextual_documentation(key) ⇒ Object

Returns a key if it exists and is documentable



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

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.



182
183
184
185
186
 
# File 'lib/brainstem/api_docs/endpoint.rb', line 182

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.



217
218
219
 
# File 'lib/brainstem/api_docs/endpoint.rb', line 217

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

#evaluate_field_name(field_name_or_proc) ⇒ Object Also known as: evaluate_root_name

Evaluate field name if proc and symbolize it.



162
163
164
165
166
167
 
# File 'lib/brainstem/api_docs/endpoint.rb', line 162

def evaluate_field_name(field_name_or_proc)
  return field_name_or_proc if field_name_or_proc.nil?

  field_name = field_name_or_proc.respond_to?(:call) ? field_name_or_proc.call(controller.const) : field_name_or_proc
  field_name.to_sym
end

#key_with_default_fallback(key) ⇒ Object 



232
233
234
 
# File 'lib/brainstem/api_docs/endpoint.rb', line 232

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

#params_configuration_tree ⇒ Hash{Symbol => Hash}

Returns a hash of all params nested under the specified root or parent fields along with their type, item type & children.

Returns:

  • (Hash{Symbol => Hash}) —

    root keys and their type info, item info & children nested under them.



129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
 
# File 'lib/brainstem/api_docs/endpoint.rb', line 129

def params_configuration_tree
  @params_configuration_tree ||= begin
    valid_params
      .to_h
      .deep_dup
      .with_indifferent_access
      .inject(ActiveSupport::HashWithIndifferentAccess.new) do |result, (field_name_proc, field_config)|

      next result if field_config[:nodoc]

      field_name = evaluate_field_name(field_name_proc)
      if field_config.has_key?(:ancestors)
        ancestors = field_config[:ancestors].map { |ancestor_key| evaluate_field_name(ancestor_key) }

        parent = ancestors.inject(result) do |traversed_hash, ancestor_name|
          traversed_hash[ancestor_name] ||= { :_config => { type: 'hash' } }
          traversed_hash[ancestor_name]
        end

        parent[field_name] = { :_config => field_config.except(:root, :ancestors) }
      else
        result[field_name] = { :_config => field_config }
      end

      result
    end
  end
end

#presenter_title ⇒ Object 



237
238
239
 
# File 'lib/brainstem/api_docs/endpoint.rb', line 237

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.



246
247
248
249
250
251
252
253
 
# File 'lib/brainstem/api_docs/endpoint.rb', line 246

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

#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.



174
175
176
 
# File 'lib/brainstem/api_docs/endpoint.rb', line 174

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