class Brainstem::ApiDocs::Endpoint
Constants
- ACTION_ORDER
Attributes
Stores the ApiDocs::Presenter
object associated with this endpoint.
Public Class Methods
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
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
Helper for retrieving action-specific configuration from the controller.
# File lib/brainstem/api_docs/endpoint.rb, line 272 def action_configuration configuration[action] || {} end
# File lib/brainstem/api_docs/endpoint.rb, line 122 def consumes @consumes ||= key_with_default_fallback(:consumes) end
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
# File lib/brainstem/api_docs/endpoint.rb, line 114 def custom_response @custom_response ||= action_configuration[:custom_response] end
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
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
Retrieves default action context from the controller.
# File lib/brainstem/api_docs/endpoint.rb, line 279 def default_configuration configuration[:_default] || {} end
# File lib/brainstem/api_docs/endpoint.rb, line 142 def deprecated @deprecated ||= key_with_default_fallback(:deprecated) end
# File lib/brainstem/api_docs/endpoint.rb, line 106 def description @description ||= contextual_documentation(:description) || "" end
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
# File lib/brainstem/api_docs/endpoint.rb, line 138 def external_docs @external_docs ||= key_with_default_fallback(:external_docs) end
# File lib/brainstem/api_docs/endpoint.rb, line 292 def key_with_default_fallback(key) action_configuration[key] || default_configuration[key] end
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
Is the entire endpoint undocumentable?
# File lib/brainstem/api_docs/endpoint.rb, line 98 def nodoc? nodoc_for?(action_configuration) end
# File lib/brainstem/api_docs/endpoint.rb, line 118 def operation_id @operation_id ||= action_configuration[:operation_id] end
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
# File lib/brainstem/api_docs/endpoint.rb, line 296 def presenter_title presenter && presenter.title end
# File lib/brainstem/api_docs/endpoint.rb, line 126 def produces @produces ||= key_with_default_fallback(:produces) end
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
# File lib/brainstem/api_docs/endpoint.rb, line 134 def schemes @schemes ||= key_with_default_fallback(:schemes) end
# File lib/brainstem/api_docs/endpoint.rb, line 130 def security @security ||= key_with_default_fallback(:security) end
# File lib/brainstem/api_docs/endpoint.rb, line 102 def title @title ||= contextual_documentation(:title) || action.to_s.humanize end
Pretty prints each endpoint.
# File lib/brainstem/api_docs/endpoint.rb, line 48 def to_s "#{http_methods.join(" / ")} #{path}" end
Brainstem::Concerns::Formattable#valid_options
# File lib/brainstem/api_docs/endpoint.rb, line 19 def valid_options super | [ :path, :http_methods, :controller, :controller_name, :action, :presenter, :include_internal ] end
# File lib/brainstem/api_docs/endpoint.rb, line 110 def valid_params @valid_params ||= key_with_default_fallback(:valid_params) end
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
# File lib/brainstem/api_docs/endpoint.rb, line 315 def nodoc_for?(config) !!(config[:nodoc] || (config[:internal] && !include_internal)) end