class Apiculture::MethodDocumentation

Generates Markdown/HTML documentation about a single API action.

Formats route parameters and request/QS parameters as a neat HTML table, listing types, requirements and descriptions.

Is used by AppDocumentation to compile a document on the entire app’s API structure in one go.

Public Class Methods

new(action_definition, mountpoint = '') click to toggle source
# File lib/apiculture/method_documentation.rb, line 12
def initialize(action_definition, mountpoint = '')
  @definition = action_definition
  @mountpoint = mountpoint
end

Public Instance Methods

to_html_fragment() click to toggle source

Compose an HTML string by converting the result of to_markdown

# File lib/apiculture/method_documentation.rb, line 30
def to_html_fragment
  markdown_string_to_html(to_markdown)
end
to_markdown() click to toggle source

Compose a Markdown definition of the action

# File lib/apiculture/method_documentation.rb, line 18
def to_markdown
  m = MDBuf.new
  m << "## #{@definition.http_verb.upcase} #{@mountpoint}#{@definition.path}"
  m << @definition.description
  m << route_parameters_table
  m << request_parameters_table
  m << possible_responses_table

  m.to_s
end

Private Instance Methods

_route_parameters_table() click to toggle source
# File lib/apiculture/method_documentation.rb, line 50
def _route_parameters_table
  return '' unless @definition.defines_route_params?

  m = MDBuf.new
  b = StringBuf.new
  m << '### URL parameters'

  html = Builder::XmlMarkup.new(:target => b)
  html.table(class: 'apiculture-table') do
    html.tr do
      html.th 'Name'
      html.th 'Description'
    end

    @definition.route_parameters.each do | param |
      html.tr do
        html.td { html.tt(':%s' % param.name) }
        html.td { html << markdown_string_to_html(param.description) }
      end
    end
  end
  m << b.to_s
end
body_example(for_response_definition) click to toggle source
# File lib/apiculture/method_documentation.rb, line 74
def body_example(for_response_definition)
  if for_response_definition.no_body?
    '(empty)'
  else
    begin
      JSON.pretty_generate(for_response_definition.jsonable_object_example)
    rescue JSON::GeneratorError
      # pretty_generate refuses to generate scalars
      # it wants objects or arrays. For bare JSON values .dump will do
      JSON.dump(for_response_definition.jsonable_object_example)
    end
  end
end
markdown_string_to_html(str) click to toggle source
# File lib/apiculture/method_documentation.rb, line 36
def markdown_string_to_html(str)
  RDiscount.new(str.to_s).to_html
end
parameters_table(parameters) click to toggle source
# File lib/apiculture/method_documentation.rb, line 131
def parameters_table(parameters)
  b = StringBuf.new
  html = Builder::XmlMarkup.new(:target => b)
  html.table(class: 'apiculture-table') do
    html.tr do
      html.th 'Name'
      html.th 'Required'
      html.th 'Type after cast'
      html.th 'Description'
    end

    parameters.each do | param |
      html.tr do
        html.td { html.tt(param.name.to_s) }
        html.td(param.required ? 'Yes' : 'No')
        html.td(param.matchable.inspect)
        html.td { html << markdown_string_to_html(param.description) }
      end
    end
  end
  b
end
possible_responses_table() click to toggle source
# File lib/apiculture/method_documentation.rb, line 88
def possible_responses_table
  return '' unless @definition.defines_responses?

  m = MDBuf.new
  b = StringBuf.new
  m << '### Possible responses'

  html = Builder::XmlMarkup.new(:target => b)
  html.table(class: 'apiculture-table') do
    html.tr do
      html.th('HTTP status code')
      html.th('What happened')
      html.th('Example response body')
    end

    @definition.responses.each do | resp |
      html.tr do
        html.td { html.b(resp.http_status_code) }
        html.td { html << markdown_string_to_html(resp.description) }
        html.td { html.pre { html.code(body_example(resp)) }}
      end
    end
  end

  m << b.to_s
end
request_parameters_table() click to toggle source
# File lib/apiculture/method_documentation.rb, line 115
def request_parameters_table
  return '' unless @definition.defines_request_params?
  m = MDBuf.new
  m << '### Request parameters'
  m << parameters_table(@definition.parameters).to_s
end
route_parameters_table() click to toggle source
# File lib/apiculture/method_documentation.rb, line 122
def route_parameters_table
  return '' unless @definition.defines_route_params?
  m = MDBuf.new
  m << '### URL parameters'
  m << parameters_table(@definition.route_parameters).to_s
end