class Brainstem::ApiDocs::Endpoint

Constants

ACTION_ORDER

Attributes

action[RW]
atlas[RW]
controller[RW]
controller_name[RW]
http_methods[RW]
include_internal[RW]
path[RW]
presenter[RW]

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

Public Class Methods

new(atlas, options = {}) { |self| ... } click to toggle source
Calls superclass method Brainstem::Concerns::Optional::new
# File lib/brainstem/api_docs/endpoint.rb, line 31
def initialize(atlas, options = {})
  self.atlas = atlas
  super options
  yield self if block_given?
end

Public Instance Methods

<=>(other) click to toggle source

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.

# File lib/brainstem/api_docs/endpoint.rb, line 68
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() click to toggle source

Helper for retrieving action-specific configuration from the controller.

# File lib/brainstem/api_docs/endpoint.rb, line 272
def action_configuration
  configuration[action] || {}
end
consumes() click to toggle source
# File lib/brainstem/api_docs/endpoint.rb, line 122
def consumes
  @consumes ||= key_with_default_fallback(:consumes)
end
contextual_documentation(key) click to toggle source

Returns a key if it exists and is documentable

# File lib/brainstem/api_docs/endpoint.rb, line 286
def contextual_documentation(key)
  action_configuration.has_key?(key) &&
    !nodoc_for?(action_configuration[key]) &&
    action_configuration[key][:info]
end
custom_response() click to toggle source
# File lib/brainstem/api_docs/endpoint.rb, line 114
def custom_response
  @custom_response ||= action_configuration[:custom_response]
end
custom_response_configuration_tree() click to toggle source

Returns a hash of all fields for a custom response nested under the specified parent fields along with their type, item type & children.

@return [Hash{Symbol => Hash}] root keys and their type info, item info & children

nested under them.
# File lib/brainstem/api_docs/endpoint.rb, line 190
def custom_response_configuration_tree
  return {} unless custom_response.present?

  @custom_response_configuration ||= begin
    custom_response_fields = custom_response
      .to_h
      .deep_dup
      .with_indifferent_access
    custom_config_tree = ActiveSupport::HashWithIndifferentAccess.new
    custom_config_tree[:_config] = custom_response_fields[:_config]

    custom_response_fields
      .except(:_config)
      .inject(custom_config_tree) do |result, (field_name_proc, field_config)|

      next result if nodoc_for?(field_config)
      field_config = field_config.except(:nodoc, :internal)

      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(:ancestors) }
      else
        result[field_name] = { :_config => field_config }
      end

      result
    end
  end
end
declared_presented_class() click to toggle source

Used to retrieve this endpoint's presenter constant.

# File lib/brainstem/api_docs/endpoint.rb, line 248
def declared_presented_class
  valid_presents.has_key?(:target_class) &&
    !nodoc_for?(valid_presents) &&
    valid_presents[:target_class]
end
default_configuration() click to toggle source

Retrieves default action context from the controller.

# File lib/brainstem/api_docs/endpoint.rb, line 279
def default_configuration
  configuration[:_default] || {}
end
deprecated() click to toggle source
# File lib/brainstem/api_docs/endpoint.rb, line 142
def deprecated
  @deprecated ||= key_with_default_fallback(:deprecated)
end
description() click to toggle source
# File lib/brainstem/api_docs/endpoint.rb, line 106
def description
  @description ||= contextual_documentation(:description) || ""
end
evaluate_field_name(field_name_or_proc) click to toggle source

Evaluate field name if proc and symbolize it.

# File lib/brainstem/api_docs/endpoint.rb, line 230
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
Also aliased as: evaluate_root_name
evaluate_root_name(field_name_or_proc)
Alias for: evaluate_field_name
external_docs() click to toggle source
# File lib/brainstem/api_docs/endpoint.rb, line 138
def external_docs
  @external_docs ||= key_with_default_fallback(:external_docs)
end
key_with_default_fallback(key) click to toggle source
# File lib/brainstem/api_docs/endpoint.rb, line 292
def key_with_default_fallback(key)
  action_configuration[key] || default_configuration[key]
end
merge_http_methods!(methods) click to toggle source

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

# File lib/brainstem/api_docs/endpoint.rb, line 55
def merge_http_methods!(methods)
  self.http_methods |= methods
end
nodoc?() click to toggle source

Is the entire endpoint undocumentable?

# File lib/brainstem/api_docs/endpoint.rb, line 98
def nodoc?
  nodoc_for?(action_configuration)
end
operation_id() click to toggle source
# File lib/brainstem/api_docs/endpoint.rb, line 118
def operation_id
  @operation_id ||= action_configuration[:operation_id]
end
params_configuration_tree() click to toggle source

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

@return [Hash{Symbol => Hash}] root keys and their type info, item info & children

nested under them.
# File lib/brainstem/api_docs/endpoint.rb, line 153
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 nodoc_for?(field_config)
      field_config = field_config.except(:nodoc, :internal)

      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() click to toggle source
# File lib/brainstem/api_docs/endpoint.rb, line 296
def presenter_title
  presenter && presenter.title
end
produces() click to toggle source
# File lib/brainstem/api_docs/endpoint.rb, line 126
def produces
  @produces ||= key_with_default_fallback(:produces)
end
relative_presenter_path_from_controller(format) click to toggle source

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

# File lib/brainstem/api_docs/endpoint.rb, line 304
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
schemes() click to toggle source
# File lib/brainstem/api_docs/endpoint.rb, line 134
def schemes
  @schemes ||= key_with_default_fallback(:schemes)
end
security() click to toggle source
# File lib/brainstem/api_docs/endpoint.rb, line 130
def security
  @security ||= key_with_default_fallback(:security)
end
title() click to toggle source
# File lib/brainstem/api_docs/endpoint.rb, line 102
def title
  @title ||= contextual_documentation(:title) || action.to_s.humanize
end
to_s() click to toggle source

Pretty prints each endpoint.

# File lib/brainstem/api_docs/endpoint.rb, line 48
def to_s
  "#{http_methods.join(" / ")} #{path}"
end
valid_options() click to toggle source
# File lib/brainstem/api_docs/endpoint.rb, line 19
def valid_options
  super | [
    :path,
    :http_methods,
    :controller,
    :controller_name,
    :action,
    :presenter,
    :include_internal
  ]
end
valid_params() click to toggle source
# File lib/brainstem/api_docs/endpoint.rb, line 110
def valid_params
  @valid_params ||= key_with_default_fallback(:valid_params)
end
valid_presents() click to toggle source

Retrieves the presents settings.

# File lib/brainstem/api_docs/endpoint.rb, line 241
def valid_presents
  key_with_default_fallback(:presents) || {}
end

Private Instance Methods

nodoc_for?(config) click to toggle source
# File lib/brainstem/api_docs/endpoint.rb, line 315
def nodoc_for?(config)
  !!(config[:nodoc] || (config[:internal] && !include_internal))
end