easy_api_doc 0.2.1

data/app/assets/stylesheets/easy_api_doc/documentation.css

@@ -0,0 +1,47 @@
+/*
+  Place all the styles related to the matching controller here.
+  They will automatically be included in application.css.
+*/
+
+.wrapper {
+  margin-top: 60px;
+}
+
+.main h1 { margin-bottom: 0.5em; }
+
+h1 .label {
+  margin-right: 4px;
+  font-weight: normal;
+}
+
+small.pull-right {
+  float: right;
+}
+
+.response .output {
+  display: block;
+  width: 98%;
+  min-height: 400px;
+  padding: 13px;
+}
+
+table.table tbody tr.strong th {
+  background-color: #eee;
+}
+
+.input.additional {
+  display: block;
+}
+
+.authenticated .icon {
+  display: inline-block;
+  background: url(/assets/easy_api_doc/glyphicons-halflings.png) -288px -25px no-repeat;
+
+  width: 12px;
+  height: 12px;
+  margin-right: 5px;
+}
+
+textarea {
+  width: 350px;
+}

data/app/controllers/easy_api_doc/api_controller.rb

@@ -0,0 +1,13 @@
+module EasyApiDoc
+  class ApiController < EasyApiDoc::ApplicationController
+
+    def index
+      @api_versions = EasyApiDoc::ApiVersion.all
+    end
+
+    def show
+      @api_version = EasyApiDoc::ApiVersion.find(params[:id])
+    end
+
+  end
+end

data/app/controllers/easy_api_doc/application_controller.rb

@@ -0,0 +1,17 @@
+module EasyApiDoc
+  class ApplicationController < ActionController::Base
+
+    before_filter :load_versions
+
+    protected
+
+    def load_versions
+      @api_versions = EasyApiDoc::ApiVersion.all
+    end
+
+    def load_config
+      Configuration.load
+    end
+
+  end
+end

data/app/controllers/easy_api_doc/documentation_controller.rb

@@ -0,0 +1,42 @@
+module EasyApiDoc
+  class DocumentationController < EasyApiDoc::ApplicationController
+    before_filter :defaults
+
+    def namespace
+      @resources = @namespace.resources
+    end
+
+    def resource
+      @resource = @namespace.resources.find {|r| r.name == params[:resource] }
+      if @resource.nil?
+        raise "no resource #{params[:resource]}"
+      end
+      @actions = @resource.actions
+    end
+
+    def api_action
+      @resource = @namespace.resources.find {|r| r.name == params[:resource] }
+      @action = @resource.actions.find {|a| a.name == params[:api_action] }
+    end
+
+    private
+
+    def defaults
+      @api_version = EasyApiDoc::ApiVersion.find(params[:api])
+      @namespace = @api_version.namespaces.find {|ns| ns.name == params[:namespace] }
+      @meta = EasyApiDoc::ApiVersion.config['meta']
+      @app_title = @meta['app_title'] if @meta
+    end
+    # def execute_action
+    #   @api_version = EasyApiDoc::ApiVersion.find(params[:api])
+    #   @namespace = @api_version.namespaces.find {|ns| ns.name == params[:namespace] }
+    #   @resource = @namespace.resources.find {|r| r.name == params[:resource] }
+    #   @action = @resource.actions.find {|a| a.name == params[:api_action] }
+    #   params[:payload].delete(:authenticity_token)
+
+    #   res = @action.run(params[:payload], params[:remote_method], params[:format])
+    #   render params[:format].to_sym => res, :status => 200 #res[:status]
+    # end
+
+  end
+end

data/app/helpers/easy_api_doc/application_helper.rb

@@ -0,0 +1,71 @@
+require 'github/markup'
+
+module EasyApiDoc
+  module ApplicationHelper
+
+    def api_link(api)
+      api_path(:id => api.name)
+    end
+
+    def namespace_link(namespace)
+      namespace_path(:api => namespace.parents['apiversion'].name, :namespace => namespace.name)
+    end
+
+    def resource_link(resource)
+      resource_path(:api => resource.parents['apiversion'].name, :namespace => resource.parents['namespace'].name, :resource => resource.name)
+    end
+
+    def action_link(action)
+      api_action_path(:api => action.parents['apiversion'].name, :namespace => action.parents['namespace'].name, :resource => action.parents['resource'].name, :api_action => action.name)
+    end
+
+    def breadcrumbs(stack)
+      crumbs = []
+      stack.each do |name, uri|
+        if uri
+          crumbs << link_to(name, uri)
+        else
+          crumbs << name
+        end
+      end
+
+      content_tag(:ol, :class => "breadcrumb") do
+        output = ""
+        crumbs.each do |c|
+          output += content_tag(:li, c, :class => crumbs.last ? 'active' : nil)
+        end
+        output.html_safe
+      end
+    end
+
+    def contents_for_resource(resource, attribute_name)
+      tree = ['doc', 'api', resource.parents['apiversion'].name, resource.parents['namespace'].name, resource.name]
+      file = File.join(*tree, "#{attribute_name}.md")
+      if File.exists?(file)
+        GitHub::Markup.render(file, File.read(file)).html_safe
+      else
+        resource.attributes[attribute_name]
+      end
+    end
+
+    def contents_for_action(resource, action, attribute_name)
+      tree = ['doc', 'api', resource.parents['apiversion'].name, resource.parents['namespace'].name, resource.name, action.name]
+      file = File.join(*tree, "#{attribute_name}.md")
+      if File.exists?(file)
+        GitHub::Markup.render(file, File.read(file)).html_safe
+      else
+        action.attributes[attribute_name]
+      end
+    end
+
+    def example_json(key_json_file)
+      tree = ['doc', 'api', 'examples', 'json']
+      file = File.join(*tree, "#{key_json_file}")
+      if File.exists?(file)
+        File.read(file)
+      else
+        nil
+      end
+    end
+  end
+end

data/app/helpers/easy_api_doc/documentation_helper.rb

@@ -0,0 +1,5 @@
+module EasyApiDoc
+  module DocumentationHelper
+
+  end
+end

data/app/models/easy_api_doc/action.rb

@@ -0,0 +1,59 @@
+require 'net/http'
+
+module EasyApiDoc
+  class Action
+    include EasyApiDoc::Configurable
+
+    def path
+      uri = attributes['uri']
+      if host
+        "#{protocol}://#{host}#{uri}"
+      else
+        uri
+      end
+    end
+
+    # def run(params, method, format)
+    #   uri = URI(path + "." + format)
+    #   res = Net::HTTP.send(method.downcase, uri) # TODO works with get only
+    #   # {:body => res.body, :status => res.status}
+    #   res
+    # end
+
+    def parameters
+      @parameters ||= load_children(EasyApiDoc::Parameter, 'parameters')
+    end
+
+    def post_data
+      attributes['post_data']
+    end
+
+    def protocol
+      v = @parents['apiversion']
+      v.attributes['defaults']['protocol'] || 'http'
+    end
+
+    def host
+      v = @parents['apiversion']
+      if v && v.attributes['defaults']
+        v.attributes['defaults']['domain']
+      else
+        nil
+      end
+    end
+
+    def formats
+      v = inherited_overridable('formats', :from => ['resource', 'namespace'])
+      v.split(/\,\s/) if v
+    end
+
+    def authentication
+      @authentication ||= inherited_overridable('authentication', :from => ['resource', 'namespace', 'apiversion'])
+    end
+
+    def options
+      @attributes['options']
+    end
+
+  end
+end

data/app/models/easy_api_doc/api_version.rb

@@ -0,0 +1,18 @@
+module EasyApiDoc
+  class ApiVersion
+    include EasyApiDoc::Configurable
+
+    def namespaces
+      @namespaces ||= load_children(EasyApiDoc::Namespace, nil, {:exclude => ['defaults', 'meta']})
+    end
+
+    def self.config_path
+      ['api']
+    end
+
+    def authentication
+      @authentication ||= inherited_overridable('authentication', :from => ['resource', 'namespace', 'apiversion'])
+    end
+
+  end
+end

data/app/models/easy_api_doc/namespace.rb

@@ -0,0 +1,14 @@
+module EasyApiDoc
+  class Namespace
+    include EasyApiDoc::Configurable
+
+    def resources
+      @resources ||= load_children(EasyApiDoc::Resource, 'resources')
+    end
+
+    def authentication
+      @authentication ||= inherited_overridable('authentication', :from => ['resource', 'namespace', 'apiversion'])
+    end
+
+  end
+end

data/app/models/easy_api_doc/parameter.rb

@@ -0,0 +1,49 @@
+module EasyApiDoc
+  class Parameter
+    include EasyApiDoc::Configurable
+
+    attr_accessor :field_name
+
+    def initialize(*params)
+      super(*params)
+      set_field_name
+    end
+
+    def nested?
+      self['type'] == nil
+    end
+
+    def parameters
+      return [] unless nested?
+      return @parameters if @parameters
+      field_namespace = @field_namespace || []
+      field_namespace << @name
+      @parameters = load_children(EasyApiDoc::Parameter, nil, {:extra_attributes => {'field_namespace' => field_namespace}})
+    end
+
+    def scope_level
+      (@attributes['field_namespace'] || []).size
+    end
+
+    private
+
+    # Field namespace is for managing nested paramaters so that the form we output will have an input labelled correctly in our executable harness
+    # :user => {:email}
+    # will produce: 'user[email]' as the @field_name
+    # name: the name/label of this parameter (email in our example)
+    # namespaces, an array of the scopes to prepend
+    def set_field_name
+      field_namespace = @attributes['field_namespace']
+      fname = if field_namespace
+        field_namespace.map do |n|
+          n == field_namespace.first ? n : "[#{n}]"
+        end.join + "[#{@name}]"
+      else
+        @name
+      end
+      fname += '[]' if self['type'] == 'array'
+      @field_name = fname
+    end
+
+  end
+end

data/app/models/easy_api_doc/resource.rb

@@ -0,0 +1,18 @@
+module EasyApiDoc
+  class Resource
+    include EasyApiDoc::Configurable
+
+    def formats
+      inherited_overridable('formats', :from => ['namespace'])
+    end
+
+    def actions
+      @actions ||= load_children(EasyApiDoc::Action, 'actions')
+    end
+
+    def authentication
+      @authentication ||= inherited_overridable('authentication', :from => ['resource', 'namespace', 'apiversion'])
+    end
+
+  end
+end

data/app/views/easy_api_doc/api/index.html.erb

@@ -0,0 +1,5 @@
+<h1>API Versions</h1>
+
+<% @api_versions.each do |api| %>
+  <p><%= api.name %></p>
+<% end %>

data/app/views/easy_api_doc/documentation/_parameter.html.erb

@@ -0,0 +1,29 @@
+<% if parameter.nested? %>
+  <%# Nested param %>
+  <tr>
+    <td><strong><%= parameter.name %></strong></td>
+    <td>nested attributes below</td>
+    <td></td>
+    <td></td>
+    <td></td>
+    <td></td>
+    <td></td>
+  </tr>
+  <% parameter.parameters.each do |p| %>
+    <%= render :partial => 'easy_api_doc/documentation/parameter', :locals => {:parameter => p} %>
+  <% end %>
+<% else %>
+  <%# Standard parameter %>
+  <tr>
+    <td><%= raw('&#187; ' * parameter.scope_level) %> <%= parameter.name %></td>
+    <td>
+      <%= text_field_tag(parameter.field_name, (parameter['example'] || parameter['default']), :class => 'input') %>
+      <%= link_to('add another item', '#', :class => 'append-fields') if parameter['type'] == 'array' %><br />
+    </td>
+    <td><%= link_to 'disable', '#', :class => 'disable-field-toggle' %></td>
+    <td><%= parameter['type'] %></td>
+    <td><%= parameter['default'] %></td>
+    <td><%= parameter['required'] %></td>
+    <td><%= parameter['info'] %></td>
+  </tr>
+<% end %>

data/app/views/easy_api_doc/documentation/_resource_index.html.erb

@@ -0,0 +1,16 @@
+<div class="panel panel-default">
+  <div class="panel-heading">
+    <h3 class="panel-title"><%= @api_version.name %> / <%= @namespace.name %></h3>
+  </div>
+  <div class="panel-body">
+  <ul class='nav nav-list'>
+    <% @namespace.resources.each do |rs| %>
+      <li><strong><%= link_to rs.name, resource_link(rs) %></strong></li>
+      <% rs.actions.each do |ac| %>
+        <li><%= link_to ac.name, action_link(ac) %></li>
+      <% end %>
+    <% end %>
+  </ul>
+  </div>
+
+</div>

data/app/views/easy_api_doc/documentation/api_action.html.erb

@@ -0,0 +1,105 @@
+<% provide(:sidebar) do %>
+  <%= render :partial => 'resource_index' %>
+<% end %>
+
+<%= breadcrumbs([
+  [@api_version.name, api_link(@api_version)],
+  [@namespace.name, namespace_link(@namespace)],
+  [@resource.name, resource_link(@resource)],
+  [@action.name]
+]) %>
+
+<div class="panel panel-default">
+  <div class="panel-heading">
+    <h3 class="panel-title">[<%= @action.attributes['http_method'] %>] <%= @action.name %>
+  <%= @action.formats.map {|l| content_tag(:span, l, :class => 'label label-info') }.join.html_safe %>
+  <%= content_tag(:small, content_tag(:span, '', :class => 'icon') + 'authenticated', :class => 'authenticated') if @action.authentication %></h3>
+  </div>
+  <div class="panel-body">
+    <%= @action.attributes['uri'] %>
+  </div>
+</div>
+
+<div class="panel panel-default">
+  <div class="panel-heading">
+    <h3 class="panel-title">Description</h3>
+  </div>
+  <div class="panel-body">
+    <%= contents_for_action(@resource, @action, 'description') %>
+  </div>
+</div>
+
+  <%= content_tag(:form, {:class => 'api_call', :action => @action.path, :method => @action.attributes['http_method'].downcase, 'accept-charset' => 'UTF8'}) do %>
+
+  <% if @action.authentication %>
+    <table class='table table-bordered'>
+      <% auth_keys = @action.authentication.keys %>
+      <tr class='strong'>
+        <% auth_keys.each do |k| %>
+          <th><%= (k =~ /type/i) ? 'Authentication' : k %></th>
+        <% end %>
+      </tr>
+      <tr>
+        <% auth_keys.each do |k| %>
+          <td>
+            <% if  ( k =~ /type/i)  %>
+              <%= hidden_field_tag("_doc_authentication[#{k}]",  @action.authentication[k], :class => 'input') %> <%= @action.authentication[k] %>
+            <% elsif ( k =~ /password/i)%>
+              <%= password_field_tag("_doc_authentication[#{k}]",  @action.authentication[k], :class => 'input') %>
+            <% else %>
+              <%= text_field_tag("_doc_authentication[#{k}]",  @action.authentication[k], :class => 'input') %>
+            <% end %>
+          </td>
+        <% end %>
+      </tr>
+    </table>
+  <% end %>
+
+  <div class="panel panel-default">
+    <div class="panel-heading">
+      <h3 class="panel-title">Parameters<small class='pull-right'>format–<%= select_tag 'format', options_for_select(@action.formats) %></small></h3>
+    </div>
+    <div class="panel-body">
+
+      <% if @action.parameters && @action.parameters.any? %>
+      <table class='table table-bordered table-condensed'>
+        <tr class='strong'>
+          <th>Parameter</th>
+          <th>Value</th>
+          <th><%= link_to 'disable all', '#', :class => 'disable-all-toggle' %></th>
+          <th>Type</th>
+          <th>Default</th>
+          <th>Required</th>
+          <th>Info</th>
+        </tr>
+        <% @action.parameters.each do |p| %>
+          <%= render :partial => 'easy_api_doc/documentation/parameter', :locals => {:parameter => p} %>
+        <% end %>
+      </table>
+      <% end %>
+
+    </div>
+  </div>
+
+  <div class="panel panel-default">
+    <% if @action.post_data.present? %>
+      <div class="panel-heading">
+        <h3 class="panel-title">Post Data</h3>
+      </div>
+      <div class="panel-body">
+        <% content = example_json(@action.post_data['example']) || @action.post_data['json'] || {} %>
+        <%= text_area_tag :_doc_post_data, content, rows: 10, cols: 70 %>
+      </div>
+    <% end %>
+  </div>
+
+    <%= link_to 'Run example', '#', :class => 'btn btn-primary run_api_call' %> <%= image_tag("easy_api_doc/loading.gif", :class => "loading", :style => "display:none") %>
+
+    <div class='response' style="display:none;">
+      <hr>
+      <h3>Response</h3>
+      <pre>http status: <span class='http_status'></span></pre>
+      <textarea class="prettyprint output"></textarea>
+    </div>
+
+  <% end %>

data/app/views/easy_api_doc/documentation/namespace.html.erb

@@ -0,0 +1,13 @@
+<% content_for(:sidebar) do %>
+  <%= render :partial => 'resource_index' %>
+<% end %>
+
+<div class="panel panel-default">
+  <div class="panel-heading">
+    <h3 class="panel-title"><%= @api_version.name %> &gt; <%= @namespace.name %><%= content_tag(:small, content_tag(:span, '', :class => 'icon') + 'authenticated', :class => 'authenticated') if @namespace.authentication %></h3>
+  </div>
+  <div class="panel-body">
+    <p><%= @namespace.attributes['description'] %></p>
+    <p><%= @namespace.attributes['detail'] %></p>
+  </div>
+</div>

data/app/views/easy_api_doc/documentation/resource.html.erb

@@ -0,0 +1,18 @@
+<% content_for(:sidebar) do %>
+  <%= render :partial => 'resource_index' %>
+<% end %>  
+
+<div class="panel panel-default">
+  <div class="panel-heading">
+    <h3 class="panel-title"><%= @api_version.name %> / <%= @namespace.name %> / <%= @resource.name %> / <%= content_tag(:small, content_tag(:span, '', :class => 'icon') + 'authenticated', :class => 'authenticated') if @resource.authentication %></h3>
+  </div>
+  <div class="panel-body">
+    <%= contents_for_resource(@resource, 'description') %>
+  </div>
+</div>
+
+<ul class="list-group">
+  <% @actions.each do |a| %>
+    <li class="list-group-item">[<%= a.attributes['http_method'].upcase %>] <%= link_to a.name, action_link(a) %></li>
+  <% end %>
+</ul>

data/app/views/layouts/easy_api_doc/_header.html.erb

@@ -0,0 +1,23 @@
+<nav class="navbar navbar-default" role="navigation">
+  <div class="navbar-header">
+    <%= link_to @app_title || 'API Documentation', root_path, :class => 'navbar-brand' %>
+  </div>
+
+  <div class="collapse navbar-collapse navbar-ex1-collapse">
+    <ul class="nav navbar-nav">
+
+      <% @api_versions.each do |api| %>
+        <li class="dropdown">
+          <%= link_to api.name, '#', :class => 'dropdown-toggle', 'data-toggle' => 'dropdown' %>
+          <ul class="dropdown-menu">
+            <% api.namespaces.each do |ns| %>
+              <li><%= link_to ns.name, namespace_link(ns) %></li>
+            <% end %>
+          </ul>
+        </li>
+      <% end %>
+
+    </ul>
+
+  </div>
+</nav>

data/app/views/layouts/easy_api_doc/application.html.erb

@@ -0,0 +1,34 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title><%= @app_title || 'EasyApiDoc' %> </title>
+  <link rel="shortcut icon" href="<%= asset_path("easy_api_doc/favicon.ico") %>" >
+  <%= stylesheet_link_tag    "easy_api_doc/application", :media => "all" %>
+  <%= javascript_include_tag "easy_api_doc/application" %>
+  <%= csrf_meta_tags %>
+</head>
+<body>
+
+  <div class='container'>
+
+    <%= render :partial => 'layouts/easy_api_doc/header' %>
+
+    <div class='row'>
+
+      <% if sidebar = yield(:sidebar) %>
+        <div class='col-md-3 sidebar'>
+            <%= sidebar %>
+            <%#= render :partial => 'shared/versions_index' %>
+        </div>
+      <% end %>
+
+      <div class='<%= sidebar ? "col-md-9" : "col-md-12" %> main'>
+        <%= yield %>
+      </div>
+
+    </div>
+
+  </div>
+
+</body>
+</html>

data/app/views/shared/_versions_index.html.erb

@@ -0,0 +1,10 @@
+<h2>Index</h2>
+
+<ul class='nav nav-list'>
+  <% @versions.each do |version| %>
+    <li class='nav-header'><%= link_to version.name, api_path(version.name) %></li>
+    <% version.namespaces.each do |ns| %>
+      <li><%= link_to ns.name, namespace_path(:api => version.name, :namespace => ns.name) %></li>
+    <% end %>
+  <% end %>
+</ul>

data/config/routes.rb

@@ -0,0 +1,9 @@
+EasyApiDoc::Engine.routes.draw do
+
+  resources :api, :only => [:index, :show]
+  get '/api/:api/:namespace' => 'documentation#namespace',                        :as => 'namespace'
+  get '/api/:api/:namespace/:resource' => 'documentation#resource',               :as => 'resource'
+  get '/api/:api/:namespace/:resource/:api_action' => 'documentation#api_action', :as => 'api_action'
+
+  root :to => 'api#index'
+end