rapidoc 0.0.4

data/lib/rapidoc/config/rapidoc.yml

@@ -0,0 +1,4 @@
+project_name: "Project Name"
+base_url: "http://api.mydomain.com"
+company: "My company"
+year: 2013

data/lib/rapidoc/controller_extractor.rb

@@ -0,0 +1,54 @@
+module Rapidoc
+
+  ##
+  # This class open controller file and get all documentation blocks.
+  # Lets us check if any of this blocks is a `rapidoc` block
+  # and return it using `json` format.
+  #
+  # Rapidoc blocks must:
+  # - have YAML format
+  # - begin with `#=begin action` for actions description
+  # - begin with `#=begin resource` for resource description
+  # - end with `#=end`
+  #
+  class ControllerExtractor
+
+    def initialize( controller_file )
+      lines = IO.readlines( controller_dir( controller_file ) )
+      blocks = extract_blocks( lines )
+
+      @resource_info = YamlParser.extract_resource_info( lines, blocks )
+      @actions_info = YamlParser.extract_actions_info( lines, blocks )
+    end
+
+    def get_actions_info
+      @actions_info
+    end
+
+    def get_action_info( action )
+      @actions_info.select{ |info| info['action'] == action.to_s }.first
+    end
+
+    def get_resource_info
+      @resource_info
+    end
+
+    def get_controller_info
+      { "description" => @resource_info["description"], "actions" => @actions_info }
+    end
+
+    private
+
+    ##
+    # Gets init and end lines of each comment block
+    #
+    def extract_blocks( lines )
+      init_doc_lines = lines.each_index.select{ |i| lines[i].include? "=begin" }
+      end_doc_lines = lines.each_index.select{ |i| lines[i].include? "=end" }
+
+      blocks = init_doc_lines.each_index.map do |i|
+        { :init => init_doc_lines[i], :end => end_doc_lines[i] }
+      end
+    end
+  end
+end

data/lib/rapidoc/http_response.rb

@@ -0,0 +1,61 @@
+# encoding: utf-8
+
+module Rapidoc
+
+  ##
+  # Represent http status code with code and description.
+  # Also include bootstrap label for code.
+  #
+  class HttpResponse
+
+    attr_reader :code, :description, :label
+
+    def initialize( code )
+      @code = code
+      @description = get_description
+      @label = get_label
+    end
+
+    def get_description
+      case @code
+        when 200
+          'OK'
+        when 201
+          'Created'
+        when 204
+          'No content'
+        when 401
+          'Unauthorized'
+        when 403
+          'Forbidden'
+        when 404
+          'Not found'
+        when 422
+          'Unprocessable Entity'
+        else
+          ''
+      end
+    end
+
+    def get_label
+      case @code
+        when 200
+          'label label-info'
+        when 201
+          'label label-success'
+        when 204
+          'label label-info2'
+        when 401
+          'label label-warning'
+        when 403
+          'label label-warning2'
+        when 422
+          'label label-important'
+        when 404
+          'label label-inverse'
+        else
+          'label'
+      end
+    end
+  end
+end

data/lib/rapidoc/param_errors.rb

@@ -0,0 +1,43 @@
+module Rapidoc
+
+  module ParamErrors
+
+    def get_error_info( object, type )
+      case type
+      when 'required'
+        get_required_error_info object
+      when 'inclusion'
+        get_inclusion_error_info object
+      else
+        nil
+      end
+    end
+
+    def get_required_error_info( object )
+      if default_errors and default_errors.include? "required"
+        get_default_error_info( object, "required" )
+      else
+        {  "object" => object,
+           "message" => "blank", 
+           "description" => "This parameter is mandatory" }
+      end
+    end
+
+    def get_inclusion_error_info( object )
+      if default_errors and default_errors.include? "inclusion"
+        get_default_error_info( object, "inclusion" )
+      else
+        { "object" => object, 
+          "message" => "inclusion",
+          "description" => "This parameter is not in the collection" }
+      end
+    end
+
+    def get_default_error_info( object, type )
+      { 'object' => object,
+        'message' => default_errors[type]['message'],  # config function
+        'description' => default_errors[type]['description']
+      }
+    end
+  end
+end

data/lib/rapidoc/resource_doc.rb

@@ -0,0 +1,66 @@
+# encoding: utf-8
+
+module Rapidoc
+
+  ##
+  # This class includes all info about a resource
+  # To extract info from controller file uses ControllerExtractor
+  # It includes an array of ActionDoc with each action information
+  #
+  class ResourceDoc
+    attr_reader :name, :description, :controller_file, :actions_doc
+
+    ##
+    # @param resource_name [String] resource name
+    # @param routes_doc [RoutesDoc] routes documentation
+    #
+    def initialize( resource_name, routes_actions_info )
+      @name = resource_name.to_s
+      @controller_file = name.to_s.pluralize + '_controller.rb'
+
+      generate_info routes_actions_info
+    end
+
+    ##
+    # Names with '/' caracter produce problems in html ids
+    #
+    def simple_name
+      return self.name.delete '/'
+    end
+
+    private
+
+    ##
+    # Create description and actions_doc
+    #
+    def generate_info( routes_info )
+      if routes_info
+        extractor = get_controller_extractor
+        @description = extractor.get_resource_info['description'] if extractor
+        @actions_doc =  get_actions_doc( routes_info, extractor )
+      end
+    end
+
+    ##
+    # @return [ControllerExtractor] extractor that allow read controller files
+    # and extract action and resource info from them
+    #
+    def get_controller_extractor
+      if File.exists? controller_dir( @controller_file )
+        ControllerExtractor.new @controller_file
+      else
+        nil
+      end
+    end
+
+    ##
+    # @return [Array] all the resource ActionDoc
+    #
+    def get_actions_doc( routes_actions_info, extractor )
+      routes_actions_info.map do |route_info|
+        controller_info = extractor ? extractor.get_action_info( route_info[:action] ) : nil
+        ActionDoc.new( route_info, controller_info, examples_dir )
+      end
+    end
+  end
+end

data/lib/rapidoc/resources_extractor.rb

@@ -0,0 +1,42 @@
+module Rapidoc
+
+  ##
+  # This module get resources info.
+  #
+  # Info of each route include:
+  # - method
+  # - action
+  # - url
+  # - controller_file
+  #
+  module ResourcesExtractor
+
+    ##
+    # Reads 'rake routes' output and gets the routes info
+    # @return [RoutesDoc] class with routes info
+    #
+    def get_routes_doc
+      routes_doc = RoutesDoc.new
+      routes = Dir.chdir( ::Rails.root.to_s ) { `rake routes` }
+
+      routes.split("\n").each do |entry|
+        routes_doc.add_route( entry )
+      end
+
+      routes_doc
+    end
+
+    ##
+    # Create new ResourceDoc for each resource extracted from RoutesDoc
+    # @return [Array] ResourceDoc array
+    #
+    def get_resources
+      routes_doc = get_routes_doc
+      resources_names = routes_doc.get_resources_names - resources_black_list
+
+      resources_names.map do |resource|
+        ResourceDoc.new( resource, routes_doc.get_actions_route_info( resource ) )
+      end
+    end
+  end
+end

data/lib/rapidoc/routes_doc.rb

@@ -0,0 +1,96 @@
+# encoding: utf-8
+
+module Rapidoc
+
+  ##
+  # This class let us manage resources and actions extracted from 'rake routes'
+  #
+  class RoutesDoc
+    def initialize
+      @resources_routes = {}
+    end
+
+    def add_route( route )
+      if route.split.size == 4
+        method, url, controller_action = route.split.slice(1, 3)
+      else
+        method, url, controller_action = route.split
+      end
+
+      add_resource_route( method, url, controller_action )
+    end
+
+    def get_resources_names
+      @resources_routes.keys.sort
+    end
+
+    def get_resource_actions_names( resource )
+      @resources_routes[resource.to_sym].map{ |route| route[:action] }.uniq
+    end
+
+    def get_actions_route_info( resource )
+      get_resource_actions_names( resource ).map do |action|
+        get_action_route_info( resource, action )
+      end
+    end
+
+    def get_action_route_info( resource, action )
+      urls = []
+      controllers = []
+      methods = []
+
+      # compact and generate action info from all routes info of resource
+      @resources_routes[resource.to_sym].each do |route|
+        if route[:action] == action.to_s
+          urls.push route[:url]
+          controllers.push route[:controller]
+          methods.push route[:method]
+        end
+      end
+
+      return {
+        resource: resource.to_s,
+        action: action.to_s,
+        method: methods.uniq.first,
+        urls: urls.uniq,
+        controllers: controllers.uniq
+      }
+    end
+
+    private
+
+    ##
+    # Add new route info to resource routes array with correct format
+    #
+    def add_resource_route( method, url, controller_action )
+      #resource = get_resource_name( url )
+      resource = controller_action.split('#').first
+      info =  {
+        resource: resource,
+        action: controller_action.split('#').last,
+        method: method,
+        url: url ,
+        controller: controller_action.split('#').first
+      }
+
+      @resources_routes[resource.to_sym] ||= []
+      @resources_routes[resource.to_sym].push( info )
+    end
+
+    ##
+    # Extract resource name from url
+    #
+    def get_resource_name( url )
+      new_url = url.gsub( '(.:format)', '' )
+
+      return $1 if new_url =~ /\/(\w+)\/:id$/         # /users/:id (users)
+      return $1 if new_url =~ /\/(\w+)\/:id\/edit$/   # /users/:id/edit (users)
+      return $1 if new_url =~ /^\/(\w+)$/             # /users  (users)
+      return $1 if new_url =~ /\/:\w*id\/(\w+)$/      # /users/:id/images (images)
+      return $1 if new_url =~ /\/:\w*id\/(\w+)\/\w+$/ # /users/:id/config/edit (users)
+      return $1 if new_url =~ /^\/(\w+)\/\w+$/        # /users/edit (users)
+      return $1 if new_url =~ /\/(\w+)\/\w+\/\w+$/    # /users/password/edit (users)
+      return url
+    end
+  end
+end

data/lib/rapidoc/templates/action.html.hbs

@@ -0,0 +1,170 @@
+<!DOCTYPE html>
+<html lang="es">
+  <head>
+    <meta charset="utf-8">
+    <title>Rapidoc - Action</title>
+    <meta name="description" content="Artículo en GenbetaDev sobre Bootstrap 2.0">
+    <meta name="author" content="Rafael Jurado González" >
+    <link href="../assets/css/bootstrap.min.css" rel="stylesheet">
+    <link href="../assets/css/rapidoc.css" rel="stylesheet">
+    <link href="../assets/css/bootstrap-responsive.min.css" rel="stylesheet">
+    <script src="../assets/js/jquery-1.9.0.min.js"></script>
+    <script src="../assets/js/bootstrap.min.js"></script>
+    <script src="../assets/js/json2.js"></script>
+    <style>
+      body { padding-top: 60px; }
+    </style>
+  </head>
+  <body onload="prueba()">
+
+    <div class="navbar navbar-fixed-top">
+      <div class="navbar-inner">
+        <div class="container">
+          <a class="btn btn-navbar" data-toggle="collapse" data-target=".nav-collapse">
+            <span class="icon-bar"></span>
+            <span class="icon-bar"></span>
+            <span class="icon-bar"></span>
+          </a>
+          <a class="brand" href="#">{{info.project_name}}</a>
+          <div class="nav-collapse">
+            <ul class="nav">
+              <li><a href="../index.html">Resources</a></li>
+              <li class="active"><a href="#">Action</a></li>
+              <li><a target="_blank" href="https://github.com/drinor/rapidoc.git">Contact</a></li>
+            </ul>
+          </div>
+        </div>
+      </div>
+    </div>
+
+    <div class="container">
+      <div class="page-header">
+        <h1>{{action.resource}}</h1>
+      </div>
+
+      <ul class="nav nav-tabs" id="myTab">
+        <li class="active"><a href="#home">Home</a></li>
+        {{#if action.params}}<li><a href="#params">Params</a></li>{{/if}}
+        {{#if action.errors}}<li><a href="#errors">Errors</a></li>{{/if}}
+        {{#if action.example_req}}<li><a href="#request">Request</a></li>{{/if}}
+        {{#if action.example_res}}<li><a href="#response">Response</a></li>{{/if}}
+      </ul>
+
+      <div class="tab-content">
+        <div class="tab-pane active my_tab" id="home">
+          <p>
+            {{action.description}}
+          </p>
+            <table class="table table-hover action-options">
+            <tr>
+              <td>Action</td><td>{{action.action}}</td>
+            </tr>
+            <tr>
+              <td>Method</td><td>{{action.action_method}}</td>
+            </tr>
+            <tr>
+              <td class="routes">Required authentication</td>
+              <td>
+                {{#if action.authentication}}
+                  <i class="icon-ok"></i>
+                {{else}}
+                  <i class="icon-remove"></i>
+                {{/if}}
+              </td>
+            </tr>
+            <tr>
+              <td>Response formats</td><td>{{action.response_formats}}</td>
+            </tr>
+          </table>
+
+
+           <h4 class="pad_top">Resource URL</h4>
+           <pre>{{action.urls}}</pre>
+
+          <h4 class="pad_top">Response Status</h4>
+          <table class="table table-hover">
+            {{#each action.http_responses}}
+            <tr>
+              <td class="routes"><span class="{{this.label}}">{{this.code}}</span></td>
+              <td>{{this.description}}</td>
+            </tr>
+            {{/each}}
+          </table>
+        </div>
+
+        {{#if action.params}}
+        <div class="tab-pane my_tab" id="params">
+          <table class="table table-hover" id="table-params">
+            {{#each action.params}}
+              <tr>
+                <td>
+                  <strong>{{this.name}}</strong></br>
+                  {{#if this.required}}
+                    <span class="small">required</span>
+                  {{else}}
+                    <span class="small">optional</span>
+                  {{/if}}
+                </td>
+                <td>
+                  {{#if this.inclusion}}
+                    [ {{this.inclusion}} ]
+                  {{else}}
+                    {{this.type}}
+                  {{/if}}
+                </td>
+                <td>{{this.description}}</td>
+              </tr>
+            {{/each}}
+            <tr><td></td><td><td></td></tr>
+          </table>
+        </div>
+        {{/if}}
+
+        {{#if action.errors}}
+        <div class="tab-pane my_tab" id="errors">
+          <table class="table table-hover" id="table-errors">
+            <tr>
+              <th>Object</th>
+              <th>Message</th>
+              <th>Description</th>
+            </tr>
+            {{#each action.errors}}
+              <tr>
+                <td>{{this.object}}</td>
+                <td>{{this.message}}</td>
+                <td>{{this.description}}</td>
+              </tr>
+            {{/each}}
+          </table>
+        </div>
+        {{/if}}
+
+        {{#if action.example_req}}
+        <div class="tab-pane my_tab" id="request">
+          <pre>{{action.example_req }}</pre>
+        </div>
+        {{/if}}
+
+        {{#if action.example_res}}
+        <div class="tab-pane my_tab" id="response">
+          <pre>{{action.example_res }}</pre>
+        </div>
+        {{/if}}
+      </div>
+
+      <script>
+        $(function () {
+          $('#myTab a:first').tab('show');
+        })
+
+        $('#myTab a').click(function (e) {
+          e.preventDefault();
+          $(this).tab('show');
+        })
+      </script>
+      <footer>
+        <p>{{info.company}} {{info.year}}</p>
+      </footer>
+    </div>
+  </body>
+</html>