class Brainstem::ApiDocs::Formatters::Markdown::EndpointFormatter

Attributes

endpoint[RW]
output[RW]

Public Class Methods

new(endpoint, options = {}) click to toggle source

Public API

# File lib/brainstem/api_docs/formatters/markdown/endpoint_formatter.rb, line 21
def initialize(endpoint, options = {})
  self.endpoint = endpoint
  self.output   = ""

  super options
end

Public Instance Methods

call() click to toggle source
# File lib/brainstem/api_docs/formatters/markdown/endpoint_formatter.rb, line 31
def call
  return output if endpoint.nodoc?

  format_title!
  format_description!
  format_endpoint!
  format_params!
  format_presents!

  output
end

Private Instance Methods

format_custom_response_message(response_config) click to toggle source
# File lib/brainstem/api_docs/formatters/markdown/endpoint_formatter.rb, line 165
def format_custom_response_message(response_config)
  result = "The resulting JSON is "
  result << case response_config[:type]
    when "array"
      if response_config[:item_type] == "hash"
        "an array of objects with the following properties"
      else
        "an array of #{response_config[:item_type].pluralize}"
      end
    when "hash"
      "a hash with the following properties"
    else
      "a #{response_config[:type]}"
  end

  result
end
format_description!() click to toggle source

Formats the description if given.

# File lib/brainstem/api_docs/formatters/markdown/endpoint_formatter.rb, line 60
def format_description!
  output << md_p(endpoint.description) unless endpoint.description.empty?
end
format_endpoint!() click to toggle source

Formats the actual URI and stated HTTP methods.

# File lib/brainstem/api_docs/formatters/markdown/endpoint_formatter.rb, line 67
def format_endpoint!
  http_methods = endpoint.http_methods.map(&:upcase).join(" / ")
  path = endpoint.path.gsub('(.:format)', '.json')
  output << md_code("#{http_methods} #{path}")
end
format_param_tree!(buffer, param_name, param_config, indentation = 0) click to toggle source

Formats the parent parameter and its children

# File lib/brainstem/api_docs/formatters/markdown/endpoint_formatter.rb, line 91
def format_param_tree!(buffer, param_name, param_config, indentation = 0)
  buffer += parameter_with_indent_level(
    param_name,
    param_config[:_config],
    indentation
  )

  children = param_config.except(:_config) || []
  children.each do |child_param_name, child_param_config|
    buffer = format_param_tree!(buffer, child_param_name, child_param_config, indentation + 1)
  end

  buffer
end
format_params!() click to toggle source

Formats each parameter.

# File lib/brainstem/api_docs/formatters/markdown/endpoint_formatter.rb, line 76
def format_params!
  return unless endpoint.params_configuration_tree.any?

  output << md_h5("Valid Parameters")
  output << md_ul do
    endpoint.params_configuration_tree.inject("") do |buff, (param_name, param_config)|
      buff << format_param_tree!("", param_name, param_config)
      buff
    end
  end
end
format_presents!() click to toggle source

Formats the data model for the action.

# File lib/brainstem/api_docs/formatters/markdown/endpoint_formatter.rb, line 143
def format_presents!
  if endpoint.custom_response.present?
    response_configuration_tree = endpoint.custom_response_configuration_tree
    response_structure_config = response_configuration_tree[:_config]

    output << md_p(format_custom_response_message(response_structure_config))
    output << md_ul do
      response_configuration_tree.except(:_config).inject("") do |buff, (param_name, param_config)|
        buff << format_param_tree!("", param_name, param_config)
        buff
      end
    end
  elsif endpoint.presenter
    output << md_h5("Data Model")

    link = md_a(endpoint.presenter_title, endpoint.relative_presenter_path_from_controller(:markdown))
    output << md_ul do
      md_li(link)
    end
  end
end
format_title!() click to toggle source

Formats the title as given, falling back to the humanized action name.

# File lib/brainstem/api_docs/formatters/markdown/endpoint_formatter.rb, line 53
def format_title!
  output << md_h4(endpoint.title)
end
parameter_with_indent_level(title, options = {}, indent = 0) click to toggle source

Formats a given parameter with a variable indent level. Useful for indifferently formatting root / nested parameters.

@param [String] name the param name @param [Hash] options information pertinent to the param @option options [Boolean] :required @option options [Boolean] :legacy @option options [Boolean] :recursive @option options [String, Symbol] :only Deprecated: use actions block instead @option options [String] :info the doc string for the param @option options [String] :type The type of the field. e.g. string, integer, boolean, array, hash @option options [String] :item_type The type of the items in the field.

Ideally used when the type of the field is an array or hash.

@param [Integer] indent how many levels the output should be indented from normal

# File lib/brainstem/api_docs/formatters/markdown/endpoint_formatter.rb, line 122
def parameter_with_indent_level(title, options = {}, indent = 0)
  options = options.dup
  text    = md_inline_code(title)

  text += md_inline_type(options.delete(:type), options.delete(:item_type)) if options.has_key?(:type)
  text += " - #{options.delete(:info)}" if options.has_key?(:info)

  if options.keys.any?
    text += "\n"
    text += md_li("Required: #{options[:required].to_s}",   indent + 1) if options.has_key?(:required) && options[:required]
    text += md_li("Legacy: #{options[:legacy].to_s}",       indent + 1) if options.has_key?(:legacy)
    text += md_li("Recursive: #{options[:recursive].to_s}", indent + 1) if options.has_key?(:recursive)
    text.chomp!
  end

  md_li(text, indent)
end