fdoc 0.2.1

data/lib/fdoc/presenters/service_presenter.rb

@@ -0,0 +1,56 @@
+# An HtmlPresenter for Fdoc::Service
+class Fdoc::ServicePresenter < Fdoc::HtmlPresenter
+  attr_reader :service
+
+  def initialize(service, options = {})
+    super(options)
+    @service = service
+  end
+
+  def to_html
+    render_erb('service.html.erb')
+  end
+
+  def name_as_link(options = {})
+    path = service.meta_service ? index_path(slug_name) : index_path
+    '<a href="%s">%s %s</a>' % [ path, options[:prefix], service.name ]
+  end
+
+  def slug_name
+    service.name.downcase.gsub(/[ \/]/, '_')
+  end
+
+  def url(extension = ".html")
+    '%s-%s%s' % [ @endpoint.path, @endpoint.verb, extension ]
+  end
+
+  def endpoints
+    if !@endpoints
+      @endpoints = []
+      prefix = nil
+
+      service.endpoints.sort_by(&:endpoint_path).each do |endpoint|
+        presenter = Fdoc::EndpointPresenter.new(endpoint, options)
+        presenter.service_presenter = self
+        presenter
+
+        current_prefix = presenter.prefix
+
+        @endpoints << [] if prefix != current_prefix
+        @endpoints.last << presenter
+
+        prefix = current_prefix
+      end
+    end
+
+    @endpoints
+  end
+
+  def description
+    render_markdown(service.description)
+  end
+
+  def discussion
+    render_markdown(service.discussion)
+  end
+end

data/lib/fdoc/service.rb

@@ -0,0 +1,88 @@
+require 'yaml'
+
+# Services represent a group of Fdoc API endpoints in a directory
+class Fdoc::Service
+  attr_reader :service_dir
+  attr_accessor :meta_service
+
+  def initialize(service_dir, scaffold_mode = Fdoc.scaffold_mode?)
+    @service_dir = File.expand_path(service_dir)
+    service_path = Dir["#{@service_dir}/*.fdoc.service"].first
+    @schema = if service_path
+      YAML.load_file(service_path)
+    elsif scaffold_mode
+      schema = {
+        'name'        => '???',
+        'basePath'    => '???',
+        'description' => '???'
+      }
+
+      Dir.mkdir(service_dir) unless Dir.exist?(service_dir)
+      service_path = "#{service_dir}/???.fdoc.service"
+      File.open(service_path, "w") { |file| YAML.dump(schema, file) }
+
+      schema
+    else
+      {}
+    end
+  end
+
+  DefaultService = self.new(Fdoc::DEFAULT_SERVICE_PATH)
+
+  # Returns an Endpoint described by (verb, path)
+  # In scaffold_mode, it will return an EndpointScaffold an of existing file
+  #   or create an empty EndpointScaffold
+  def open(verb, path, scaffold_mode = Fdoc.scaffold_mode?)
+    endpoint_path = path_for(verb, path)
+
+    if scaffold_mode
+      Fdoc::EndpointScaffold.new(endpoint_path, self)
+    else
+      Fdoc::Endpoint.new(endpoint_path, self)
+    end
+  end
+
+  def endpoint_paths
+    Dir["#{service_dir}/**/*.fdoc"]
+  end
+
+  def endpoints
+    endpoint_paths.map do |path|
+      Fdoc::Endpoint.new(path, self)
+    end
+  end
+
+  def path_for(verb, path)
+    flat_path   = File.join(@service_dir, "#{path}-#{verb.to_s.upcase}.fdoc")
+    nested_path = File.join(@service_dir, "#{path}/#{verb.to_s.upcase}.fdoc")
+
+    if File.exist?(flat_path)
+      flat_path
+    elsif File.exist?(nested_path)
+      nested_path
+    else # neither exists, default to flat_path
+      flat_path
+    end
+  end
+
+  def name
+    @schema['name']
+  end
+
+  def base_path
+    base_path = @schema['basePath']
+    if base_path && !base_path.end_with?('/')
+      base_path + '/'
+    else
+      base_path
+    end
+  end
+
+  def description
+    @schema['description']
+  end
+
+  def discussion
+    @schema['discussion']
+  end
+end

data/lib/fdoc/spec_watcher.rb

@@ -0,0 +1,48 @@
+module Fdoc
+  module SpecWatcher
+    VERBS = [:get, :post, :put, :delete]
+
+    VERBS.each do |verb|
+      define_method(verb) do |*params|
+        action, request_params = params
+        request_params ||= {}
+        result = super(*params)
+
+        path = if respond_to?(:example) # Rspec 2
+          example.metadata[:fdoc]
+        else # Rspec 1.3.2
+          opts = {}
+          __send__(:example_group_hierarchy).each do |example|
+            opts.merge!(example.options)
+          end
+          opts.merge!(options)
+          opts[:fdoc]
+        end
+
+        if path
+          response_params = begin
+            JSON.parse(response.body)
+          rescue
+            {}
+          end
+          successful = Fdoc.decide_success(response_params, response.status)
+          verify!(verb, path, request_params, response_params, response.status,
+            successful)
+        end
+
+        result
+      end
+    end
+
+    private
+
+    def verify!(verb, path, request_params, response_params, response_status,
+          successful)
+      service = Service.new(Fdoc.service_path)
+      endpoint = service.open(verb, path)
+      endpoint.consume_request(request_params, successful)
+      endpoint.consume_response(response_params, response_status, successful)
+      endpoint.persist! if endpoint.respond_to?(:persist!)
+    end
+  end
+end

data/lib/fdoc/templates/endpoint.html.erb

@@ -0,0 +1,75 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>
+      <%= title %>
+    </title>
+
+    <link rel="stylesheet" type="text/css" href="<%= css_path %>" />
+  </head>
+  <body>
+    <div id="page">
+      <div id="content">
+        <h1>
+          <%= name %>
+        </h1>
+
+        <div id="nav">
+          <% if @endpoint.service.meta_service %>
+            <a href="<%= index_path %>">
+              &#187; <%= @endpoint.service.meta_service.name %>
+            </a>
+          <% end %>
+          <% if service_presenter %>
+            <%= service_presenter.name_as_link(:prefix => '&#187;') %>
+          <% end %>
+        </div>
+
+        <%= description %>
+
+        <% if show_request? %>
+          <h2>Request</h2>
+
+          <h3>Example Request</h3>
+          <%= example_request %>
+
+          <h3>Request Parameters</h3>
+          <%= request_parameters %>
+        <% end %>
+
+        <h2>Response</h2>
+        <% if show_response? %>
+          <h3>Example Response</h3>
+          <%= example_response %>
+
+          <h3>Response Parameters</h3>
+          <%= response_parameters %>
+        <% end %>
+
+        <h3>Response Codes</h3>
+        <% if !successful_response_codes.empty? %>
+          <h4>Successful Response Codes</h4>
+          <ul>
+            <% successful_response_codes.each do |response_code| %>
+            <li>
+              <%= response_code.to_html %>
+            </li>
+            <% end %>
+          </ul>
+        <% end %>
+
+        <% if !successful_response_codes.empty? %>
+          <h4>Failure Response Codes</h4>
+          <ul>
+            <% failure_response_codes.each do |response_code| %>
+            <li>
+              <%= response_code.to_html %>
+            </li>
+            <% end %>
+          </ul>
+        <% end %>
+      </div>
+    </div>
+  </body>
+</html>
+

data/lib/fdoc/templates/meta_service.html.erb

@@ -0,0 +1,60 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>
+      <%= @meta_service.name %>
+    </title>
+
+    <link rel="stylesheet" type="text/css" href="<%= css_path %>" />
+  </head>
+  <body>
+    <div id="page">
+      <div id="content">
+        <h1>
+          <%= @meta_service.name %>
+        </h1>
+
+        <%= description %>
+
+        <h2>
+          Services
+        </h2>
+
+        <ul>
+          <% services.each do |serv| %>
+            <li>
+              <h3>
+                <%= serv.name_as_link %>
+              </h3>
+            </li>
+          <% end %>
+        </ul>
+
+        <h2>
+          Endpoints
+        </h2>
+
+        <% endpoints.each do |endpoint_ary| %>
+          <h3>
+            <%= endpoint_ary.first.prefix %>
+          </h3>
+          <ul>
+          <% endpoint_ary.each do |endpoint| %>
+            <li>
+              <%= endpoint.name_as_link %>
+            </li>
+          <% end %>
+          </ul>
+        <% end %>
+
+        <% if discussion %>
+          <h2>
+            Discussion
+          </h2>
+          <%= discussion %>
+        <% end %>
+      </div>
+    </div>
+  </body>
+</html>
+

data/lib/fdoc/templates/service.html.erb

@@ -0,0 +1,54 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>
+      <%= @service.name %>
+    </title>
+
+    <link rel="stylesheet" type="text/css" href="<%= css_path %>" />
+  </head>
+  <body>
+    <div id="page">
+      <div id="content">
+        <h1>
+          <%= @service.name %>
+        </h1>
+
+        <div id="nav">
+          <% if @service.meta_service %>
+            <a href="<%= index_path %>">
+              &#187; <%= @service.meta_service.name %>
+            </a>
+          <% end %>
+        </div>
+
+        <%= description %>
+
+        <h2>
+          Endpoints
+        </h2>
+
+        <% endpoints.each do |endpoint_ary| %>
+          <h3>
+            <%= endpoint_ary.first.prefix %>
+          </h3>
+          <ul>
+          <% endpoint_ary.each do |endpoint| %>
+            <li>
+              <%= endpoint.name_as_link %>
+            </li>          
+          <% end %>
+          </ul>
+        <% end %>
+
+        <% if discussion %>
+          <h2>
+            Discussion
+          </h2>
+          <%= discussion %>
+        <% end %>
+      </div>
+    </div>
+  </body>
+</html>
+

data/lib/fdoc/templates/styles.css

@@ -0,0 +1,63 @@
+
+body {
+  font: 11pt/14pt "Helvetica Neue", Helvetica, sans-serif;
+  margin: 0;
+  padding: 0;
+}
+
+#page {
+  background: white;
+  margin: 0 auto;
+  width: 540pt;
+}
+
+#content {
+  padding: 0 12pt 2em 12pt;
+}
+
+#nav { padding-bottom: 1em; }
+
+h1, h2 {
+  margin: 0 -12pt;
+  padding: .5em 12pt;
+  line-height: 1.2em;
+}
+
+h1 { font-weight: bold; }
+h1, h2, h3 { font-weight: 200; }
+
+a { text-decoration: none; color: #66f; }
+a:hover, a:active { text-decoration: underline; }
+
+ul {
+  list-style: square;
+}
+
+ul, ol, dl {
+  margin: .5em 0;
+}
+
+p {
+  margin: .5em 0 .5em 0;
+  padding: 0;
+}
+
+pre code { display: block; }
+tt, kbd, code {
+  font-family: Monaco, monospace;
+  font-size: 80%;
+  background: #eee;
+  padding: .1em;
+  border: 1pt solid #ddd;
+  white-space: pre-wrap;    
+}
+
+.endpoint-name {}
+.endpoint-name .verb { font-weight: bold; }
+.endpoint-name .root {}
+.endpoint-name .path { font-weight: bold; }
+
+a .endpoint-name .verb { display: inline-block; width: 3em; text-align: right; font-size:80% }
+
+.endpoint-name.deprecated { color: gray; }
+.schema ul span.deprecated { margin-left:.5em; font-size: 80%; color: red }