apiculture 0.0.12

data/lib/apiculture/action.rb

@@ -0,0 +1,46 @@
+# An Action is like a Sinatra route method wrapped in a class.
+# It gets instantiated with a number of instance variables (via keyword arguments)
+# and the Sinatra application calling the action.
+#
+# All the methods available within Sinatra are also available within the Action,
+# via method delegation (this primarily concerns methods like +request+, +env+, +params+
+# and so forth).
+#
+# The main work method is +perform+ which should return a data structure that can be converted
+# into JSON by the caller.
+class Apiculture::Action
+  # Initialize a new BasicAction, with the given Sintra application and a hash
+  # of keyword arguments that will be converted into instance variables.
+  def initialize(sinatra_app, **ivars)
+    ivars.each_pair {|k,v| instance_variable_set("@#{k}", v) }
+    @_sinatra_app = sinatra_app
+  end
+  
+  # Halt with a JSON error message (delegates to Sinatra's halt() under the hood)
+  def bail(with_error_message, status: 400, **attrs_for_json_response)
+    @_sinatra_app.json_halt(with_error_message, status: status, **attrs_for_json_response)
+  end
+  
+  # Respond to all the methods the contained Sinatra app supports
+  def respond_to_missing?(*a)
+    super || @_sinatra_app.respond_to?(*a)
+  end
+  
+  # Respond to all the methods the contained Sinatra app supports
+  def method_missing(m, *a, &b)
+    if @_sinatra_app.respond_to?(m)
+      @_sinatra_app.public_send(m, *a, &b)
+    else
+      super
+    end
+  end
+  
+  # Performs the action and returns it's result.
+  #
+  # If the action result is an Array or a Hash, it will be converted into JSON
+  # and output.
+  #
+  # If something else is returned an error will be raised.
+  def perform
+  end
+end

data/lib/apiculture/action_definition.rb

@@ -0,0 +1,30 @@
+# Describes a single API action (route). Is used internally by Apiculture.
+class Apiculture::ActionDefinition
+  attr_accessor :description
+  attr_accessor :http_verb
+  attr_accessor :path
+  
+  attr_reader :parameters
+  attr_reader :route_parameters
+  attr_reader :responses
+  
+  def all_parameter_names_as_strings
+    @parameters.map(&:name_as_string) + @route_parameters.map(&:name_as_string)
+  end
+  
+  def defines_responses?
+    @responses.any?
+  end
+  
+  def defines_request_params?
+    @parameters.any?
+  end
+  
+  def defines_route_params?
+    @route_parameters.any?
+  end
+  
+  def initialize
+    @parameters, @route_parameters, @responses = [], [], []
+  end
+end

data/lib/apiculture/app_documentation.rb

@@ -0,0 +1,54 @@
+require_relative 'method_documentation'
+require 'github/markup'
+
+class Apiculture::AppDocumentation
+  class TaggedMarkdown < Struct.new(:string, :section_class)
+    def to_markdown
+      string.to_markdown.to_s rescue string.to_s
+    end
+    
+    def to_html
+      '<section class="%s">%s</section>' % [Rack::Utils.escape_html(section_class), render_markdown(to_markdown)]
+    end
+    
+    def render_markdown(s)
+      GitHub::Markup.render('section.markdown', s.to_s)
+    end
+  end
+  
+  def initialize(app, mountpoint, action_definitions_and_markdown_segments)
+    @app_title = app.to_s
+    @mountpoint = mountpoint
+    @chunks = action_definitions_and_markdown_segments
+  end
+  
+  # Generates a Markdown string that contains the entire API documentation
+  def to_markdown
+    (['## %s' % @app_title] + to_markdown_slices).join("\n\n")
+  end
+  
+  # Generates an HTML fragment string that can be included into another HTML document
+  def to_html_fragment
+    to_markdown_slices.map do |tagged_markdown|
+      tagged_markdown.to_html
+    end.join("\n\n")
+  end
+  
+  def to_markdown_slices
+    markdown_slices = @chunks.map do | action_def_or_doc |
+      if action_def_or_doc.respond_to?(:http_verb) # ActionDefinition
+        s = Apiculture::MethodDocumentation.new(action_def_or_doc, @mountpoint).to_markdown
+        TaggedMarkdown.new(s, 'apiculture-method')
+      elsif action_def_or_doc.respond_to?(:to_markdown)
+        TaggedMarkdown.new(action_def_or_doc, 'apiculture-verbatim')
+      end
+    end
+  end
+  
+  # Generates a complete HTML document string that can be saved into a file
+  def to_html
+    require 'mustache'
+    template = File.read(__dir__ + '/app_documentation_tpl.mustache')
+    Mustache.render(template, :html_fragment => to_html_fragment)
+  end
+end

data/lib/apiculture/app_documentation_tpl.mustache

@@ -0,0 +1,103 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta name="charset" contents="utf-8">
+    <title>API documentation</title>
+    <style type="text/css">
+    html {
+      background: #f0f0f0;
+      height: 100%;
+    }
+
+    body {
+      margin: 0 0 0 1.5rem;
+      padding: 1.5rem;
+      background: #fff;
+      min-height: 100%;
+      border-left: 1px solid #ddd;
+      font-family: Arial, Helvetica, sans-serif;
+      -webkit-font-smoothing: antialiased;
+    }
+
+    h1, h2, h3, h4, h5, h6 {
+      font-family: Arial, sans-serif;
+      font-weight: normal;
+    }
+
+    h1, h2, h3, h4, h5, h6, p, table, ul, ol {
+      margin: 0 0 1rem;
+    }
+
+    h2 {
+      margin-bottom: .6rem;
+    }
+
+    h2:first-word {
+      color: red;
+    }
+
+    h3 {
+      -webkit-box-sizing: border-box;
+         -moz-box-sizing: border-box;
+              box-sizing: border-box;
+
+      margin-bottom: 0;
+      font-weight: bold;
+      background: #3F92FF;
+      max-width: 60rem;
+      font-size: .95em;
+      padding: .5rem 1rem;
+      color: #fff;
+    }
+
+    h3 + table.apiculture-table {
+      background: #F9F9F9;
+      padding: 1rem;
+      border: 1px solid #ddd;
+    }
+
+    .apiculture-table {
+      -webkit-box-sizing: border-box;
+         -moz-box-sizing: border-box;
+              box-sizing: border-box;
+
+      border-spacing: 0;
+      max-width: 60rem;
+      margin: 0 0 2rem;
+      width: 100%;
+    }
+
+    table.apiculture-table + h3,
+    table.apiculture-table + table.apiculture-table {
+      margin-top: -1rem;
+      /* decreases table bottom margin for double table */
+    }
+
+    table.apiculture-table td,
+    table.apiculture-table th {
+      vertical-align: top;
+      text-align: left;
+      font-size: .9em;
+    }
+
+    table.apiculture-table th {
+      border-bottom: 1px solid #CBCBCB;
+      padding: .2rem .5rem .5rem;
+    }
+
+    table.apiculture-table td {
+      padding: .2rem .5rem;
+    }
+
+    tt, code {
+      font-family: 'Lucida Console', Monaco, monospace;
+      font-weight: normal;
+      font-size: .9em;
+    }
+    </style>
+  </head>
+  
+  <body>
+    {{& html_fragment }}
+  </body>
+</html>

data/lib/apiculture/markdown_segment.rb

@@ -0,0 +1,6 @@
+# Just a tiny String container for literal documentation chunks
+class Apiculture::MarkdownSegment < Struct.new(:string)
+  def to_markdown
+    string.to_s
+  end
+end

data/lib/apiculture/method_documentation.rb

@@ -0,0 +1,130 @@
+require 'builder'
+# 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.
+class Apiculture::MethodDocumentation
+  def initialize(action_definition, mountpoint = '')
+    @definition = action_definition
+    @mountpoint = mountpoint
+  end
+  
+  # Compose a Markdown definition of the action
+  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
+  
+  # Compose an HTML string by converting the result of +to_markdown+
+  def to_html_fragment
+    require 'rdiscount'
+    RDiscount.new(to_markdown).to_html
+  end
+  
+  private
+  
+  class StringBuf #:nodoc:
+    def initialize; @blocks = []; end
+    def <<(block); @blocks << block.to_s; self; end
+    def to_s; @blocks.join; end
+  end
+  
+  class MDBuf < StringBuf  #:nodoc:
+    def to_s; @blocks.join("\n\n"); end
+  end
+  
+  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(param.description)
+        end
+      end
+    end
+    m << b.to_s
+  end
+  
+  def body_example(for_response_definition)
+    if for_response_definition.no_body?
+      '(empty)'
+    else
+      JSON.pretty_generate(for_response_definition.jsonable_object_example)
+    end
+  end
+  
+  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 resp.description
+          html.td { html.pre { html.code(body_example(resp)) }}
+        end
+      end
+    end
+    
+    m << b.to_s
+  end
+  
+  def request_parameters_table
+    return '' unless @definition.defines_request_params?
+    
+    m = MDBuf.new
+    m << '### Request 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
+      
+      @definition.parameters.each do | param |
+        html.tr do
+          html.td { html.tt(param.name.to_s) }
+          html.td(param.required ? 'Yes' : 'No')
+          html.td(param.ruby_type.to_s)
+          html.td(param.description.to_s)
+        end
+      end
+    end
+    m << b
+  end
+end

data/lib/apiculture/sinatra_instance_methods.rb

@@ -0,0 +1,36 @@
+require 'json'
+
+# Some sugary methods for use within Sinatra, when responding to a request/rendering JSON
+module Apiculture::SinatraInstanceMethods
+  NEWLINE = "\n"
+  
+  # Convert the given structure to JSON, set the content-type and
+  # return the JSON string
+  def json_response(structure)
+    content_type :json
+    JSON.pretty_generate(structure)
+  end
+  
+  # Bail out from an action by sending a halt() via Sinatra. Is most useful for
+  # handling access denied, invalid resource and other types of situations
+  # where you don't want the request to continue, but still would like to
+  # provide a decent error message to the client that it can parse
+  # with it's own JSON means.
+  def json_halt(with_error_message, status: 400, **attrs_for_json_response)
+    # Pretty-print + newline to be terminal-friendly
+    err_str = JSON.pretty_generate({error: with_error_message}.merge(attrs_for_json_response)) + NEWLINE
+    halt status, {'Content-Type' => 'application/json'}, [err_str] 
+  end
+  
+  # Handles the given action via the given class, passing it the instance variables
+  # given in the keyword arguments
+  def action_result(action_class, **action_ivars)
+    call_result = action_class.new(self, **action_ivars).perform
+  
+    unless call_result.is_a?(Array) || call_result.is_a?(Hash)
+      raise "Action result should be an Array or a Hash, but was a #{call_result.class}"
+    end
+  
+    json_response call_result
+  end
+end

data/lib/apiculture/timestamp_promise.rb

@@ -0,0 +1,6 @@
+class Apiculture::TimestampPromise
+  def self.to_markdown
+    ts = Time.now.utc.strftime "%Y-%m-%d %H:%M"
+    "Documentation built on #{ts}"
+  end
+end

data/lib/apiculture/version.rb

@@ -0,0 +1,3 @@
+module Apiculture
+  VERSION = '0.0.12'
+end

data/spec/apiculture/action_spec.rb

@@ -0,0 +1,45 @@
+require_relative '../spec_helper'
+
+describe Apiculture::Action do
+  context '.new' do
+    it 'exposes the methods of the object given as a first argument to initialize' do
+      action_class = Class.new(described_class)
+      fake_sinatra = double('Sinatra::Base', something: 'value')
+      action = action_class.new(fake_sinatra)
+      expect(action).to respond_to(:something)
+      expect(action.something).to eq('value')
+    end
+    
+    it 'converts keyword arguments to instance variables' do
+      action_class = Class.new(described_class)
+      action = action_class.new(nil, foo: 'a string')
+      expect(action.instance_variable_get('@foo')).to eq('a string')
+    end
+  end
+  
+  it 'responds to perform()' do
+    expect(described_class.new(nil)).to respond_to(:perform)
+  end
+  
+  it 'can use bail() to throw a Sinatra halt' do
+    fake_sinatra = double('Sinatra::Base')
+    expect(fake_sinatra).to receive(:json_halt).with('Failure', status: 400) 
+    action_class = Class.new(described_class)
+    action_class.new(fake_sinatra).bail "Failure"
+  end
+  
+  it 'can use bail() to throw a Sinatra halt with a custom status' do
+    fake_sinatra = double('Sinatra::Base')
+    expect(fake_sinatra).to receive(:json_halt).with("Failure", status: 417)
+    
+    action_class = Class.new(described_class)
+    action_class.new(fake_sinatra).bail "Failure", status: 417
+  end
+  
+  it 'can use bail() to throw a Sinatra halt with extra JSON attributes' do
+    fake_sinatra = double('Sinatra::Base')
+    expect(fake_sinatra).to receive(:json_halt).with("Failure", status: 417, message: "Totale")
+    action_class = Class.new(described_class)
+    action_class.new(fake_sinatra).bail "Failure", status: 417, message: 'Totale'
+  end
+end