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