api_doc_generation 0.0.4 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 71a28c541f63c63c6e7c2f272fca44b43e14273f
-  data.tar.gz: 020955f784ca17f2bbe71dd010e87ed8e37a1b7f
+  metadata.gz: 5dd65a3e0535829684cdead694989b6925fc4dc8
+  data.tar.gz: bed4b14919575ffd572bf54cb505ecad836a5c9a
 SHA512:
-  metadata.gz: f01c633f69fa3b9e097ea7f4d196602a8c85e0c92fd023984eeb4036dcac1094e38268617ab942a973873fac3bc4f151daf1950503e1cf96a0c70ba54c63c5af
-  data.tar.gz: 0b5b2dc9495774abd017bc494983bd451c9cde1513786d726136cd0bf6668627871452f4ee9aee3ad69281eebab1b47bc95c394307d49fd0cb5907b1823ced07
+  metadata.gz: 049c508ad6dfacf37e953a0150cd805046edea284e31c71636de103aa4172b56f456412c1764588cb9bc73a3b51aece45948c24281a9939c28c000928ff872bb
+  data.tar.gz: 550ae99b642a1bc4558c0e72f13a14eff8ab04197a729110c822c5ff21874fffcfb792a45d0ee92c9b24a76aac361a3c6161a22e164ae8cea36fb46f1d351cbf

data/lib/api_doc_generation.rb

@@ -10,31 +10,39 @@ end
 
 
 module ApiDocGeneration; class Generation
-  def initialize(codes_path = nil, out_path = nil)
+  def initialize(codes_path = nil)
     codes_path ||= File.expand_path('app/controllers/api', Rails.root)
-    out_path ||= File.expand_path('tmp/api_doc.html', Rails.root)
-    controller_documents = []
+    @controller_documents = []
 
     each_api_controllers_file(codes_path) do |path|
       controller_path = path.split("app/controllers").last
       class_name = controller_path.gsub('.rb', '').classify
       klass = class_name.safe_constantize
 
-      controller_documents << generate_controller(path, klass)
+      @controller_documents << generate_controller(path, klass)
     end
-
-    generate_html_string(controller_documents)
   end
 
-  def write_to_file(out_path)
-    File.open(out_path, 'w+') do |file|
-      file.write @result
-    end
+
+  def generate_html_string
+    template = ERB.new(
+      File.read(File.expand_path('../../templates/doc.html.erb', __FILE__))
+    )
+
+    ViewHelper.render(template, {
+      :documents => @controller_documents
+    })
   end
 
 
-  def result
-    @result
+  def generate_detailed_html_string
+    template = ERB.new(
+      File.read(File.expand_path('../../templates/doc_detailed.html.erb', __FILE__))
+    )
+
+    ViewHelper.render(template, {
+      :documents => @controller_documents
+    })
   end
 
 
@@ -73,12 +81,14 @@ module ApiDocGeneration; class Generation
     {
       :path => path,
       :klass => klass.to_s,
-      :actions => actions
+      :actions => actions,
+      :about => get_controller_about(filelines, klass.to_s)
     }
   end
 
 
 
+  # {name: 'xx', desc: 'yy', Params: [{level: 1, }]}
   def generate_action(klass, action, filelines)
     document = {:name => action.to_s}
     method = klass.instance_method action
@@ -97,21 +107,7 @@ module ApiDocGeneration; class Generation
       line.gsub!(/\s*\#/, '')
       next if line =~ /^\s*$/
 
-      m = line.match(/(?<level>\s*)(?<desc>(?<key>.*?)(\:(?<val>.*?))?)$/)
-      level = m[:level].length / 2
-      desc = m[:desc].gsub(/^\s*|\s*$/, '')
-      line.gsub!(/^\s*|\:?\s*$/, '')
-
-      if level == 0
-        if tmp.length == 0 && m[:val] && m[:val].length > 0
-          document[m[:key]] = m[:val]
-        else
-          document[m[:key] + (m[:val] || '')] = tmp.reverse
-        end
-        tmp = []
-      else
-        tmp << {:level => level, :desc => desc}
-      end
+      format_line(line, tmp, document)
 
       last_line = line
     end
@@ -143,16 +139,52 @@ module ApiDocGeneration; class Generation
   end
 
 
+  def format_line(line, tmp, document)
+    m = line.match(/(?<level>\s*)(?<desc>(?<key>.*?)(\:(?<val>.*?))?)$/)
+    level = m[:level].length / 2
+    desc = m[:desc].gsub(/^\s*|\s*$/, '')
+    line.gsub!(/^\s*|\:?\s*$/, '')
 
+    if level == 0
+      if tmp.length == 0 && m[:val] && m[:val].length > 0
+        document[m[:key]] = m[:val]
+      else
+        document[m[:key] + (m[:val] || '')] = tmp.reverse.each_with_object([]) do |p, result|
+          if p[:level] >= 2 && result.last
+            result.last[:children] ||= []
+            result.last[:children] << p
+          else
+            result << p
+          end
+        end
+      end
+      tmp.clear
+    else
+      m = desc.match(/(?<name>\w+)\:?\s*((\[(?<type>.*?)\]\s*)?(?<val>.*))?$/)
+      p = {:level => level, :desc => desc}
+
+      p.merge!({
+        :name => m[:name],
+        :type => m[:type],
+        :val => m[:val]
+      }) if m
+
+      tmp << p
+    end
+  end
 
-  def generate_html_string(controller_documents)
-    template = ERB.new(
-      File.read(File.expand_path('../../templates/doc.html.erb', __FILE__))
-    )
 
-    @result = ViewHelper.render(template, {
-      :documents => controller_documents
-    })
+
+  def get_controller_about(filelines, class_name)
+    pre_line = ''
+
+    filelines.each do |line|
+      break if line =~ /class\s#{Regexp.escape(class_name)}/
+      pre_line = line
+    end
+
+    pre_line.gsub(/^\s*#\s*/, '')
   end
 
+
 end; end

data/lib/api_doc_generation/version.rb

@@ -1,3 +1,3 @@
 module ApiDocGeneration
-  VERSION = "0.0.4"
+  VERSION = "0.0.5"
 end

data/lib/api_doc_generation/view_helper.rb

@@ -24,4 +24,55 @@ module ApiDocGeneration; class ViewHelper
   def action_identifer(controller_name, action_name)
     "action-#{Digest::MD5.hexdigest(controller_name)}-#{action_name}"
   end
+
+
+  def controller_identifer(controller_name)
+    "controller-#{Digest::MD5.hexdigest(controller_name)}"
+  end
+
+
+  def format_param(param)
+    return unless param[:val].to_s =~ /^\s*$/
+
+    case param[:name]
+    when 'app_uname'
+      param[:type] = 'String'
+      param[:val] = 'app的唯一标识名，表明调用此api是在哪个app下'
+    when 'access_token'
+      param[:type] = 'String'
+      param[:val] = '请求的唯一标识，用于识别用户，用户登陆返回或是使用refresh_token换取'
+    when 'refresh_token'
+      param[:type] = 'String'
+      param[:val] = '用户登陆时返回，使用此token来取得新的access_token'
+    when 'page'
+      param[:type] = 'Integer'
+      param[:val] = '返回所有数据中的第几页'
+    when 'perpage'
+      param[:type] = 'Integer'
+      param[:val] = '返回数据每页多少条'
+    end
+  end
+
+
+  def format_error_param(param)
+    return unless param[:val].to_s =~ /^\s*$/
+
+    case param[:name]
+    when 'current_page'
+      param[:type] = 'Integer'
+      param[:val] = '当前返回数据是第几页'
+    when 'perpage'
+      param[:type] = 'Integer'
+      param[:val] = '每页返回的数据量'
+    when 'count'
+      param[:type] = 'Integer'
+      param[:val] = '数据总数量'
+    when 'items'
+      param[:type] = 'Array'
+      param[:val] = '数组中存放当前页的数据'
+    when 'total_pages'
+      param[:type] = 'Integer'
+      param[:val] = '数据的总页数'
+    end
+  end
 end; end

data/lib/rake/tasks/api_doc.rake

@@ -3,10 +3,22 @@ namespace :doc do
   task :api => :environment do
     require 'api_doc_generation'
 
+    out_format = ENV['OUT_FORMAT'] || 'detailed_html'
     codes_path = ENV['CODES_PATH'] || File.expand_path('app/controllers/api', Rails.root)
 
-    File.open("./tmp/api_doc.html", "w+") do |f|
-      f.write(ApiDocGeneration::Generation.new(codes_path).result)
+    puts out_format
+    
+    case out_format
+    when 'simple_html'
+      File.open("./tmp/api_doc.html", "w+") do |f|
+        f.write(ApiDocGeneration::Generation.new(codes_path).generate_html_string)
+      end
+    when 'detailed_html'
+      File.open("./tmp/api_detailed_doc.html", 'w+') do |f|
+        f.write(ApiDocGeneration::Generation.new(codes_path).generate_detailed_html_string)
+      end
+    else
+      puts "undefined OUT_FORMAT: '#{out_format}'"
     end
   end
 end

data/templates/doc_detailed.html.erb

@@ -0,0 +1,208 @@
+<html>
+  <head>
+    <meta http-equiv="content-type" content="text/html;charset=utf-8">
+
+    <title>Uasthree Api Documents</title>
+
+    <link href='http://twitter.github.io/bootstrap/assets/css/bootstrap.css' rel='stylesheet'>
+    <style type='text/css'>
+      .title {
+        text-align: center;
+        color: blank;
+      }
+
+      .controller, .list {
+        width: 900px;
+        border: 1px solid;
+        margin: 20px auto 40 auto;
+      }
+
+      .list {
+        padding-top: 20px;
+      }
+
+      .controller-title {
+        text-align: center;
+      }
+
+      .action {
+        margin-top: 40px;
+        padding: 20px 40px 20px 20px;
+      }
+
+      .about {
+        padding-left: 20px;
+      }
+
+      .no_print {
+        opacity: 0.4;
+      }
+
+      .no_opacity {
+        opacity: 1;
+      }
+
+      @media print {
+        .no_print {
+          display: none;
+        }
+      }
+    </style>
+
+    <script type='text/javascript' src='http://code.jquery.com/jquery-2.0.3.min.js'></script>
+    <script type='text/javascript'>
+      $(function(){
+        var no_print_class = 'no_print';
+
+        $('.print_selector').change(function(event){
+          var $this = $(this);
+          var $a = $this.next();
+          var $top = $a.parent();
+          var $target_el = $($a.attr('href'));
+
+          if ($this.is(":checked")) {
+            $top.removeClass(no_print_class)
+            $target_el.removeClass(no_print_class);
+          } else {
+            $top.addClass(no_print_class)
+            $target_el.addClass(no_print_class);
+          }
+        });
+      });
+    </script>
+  </head>
+
+  <body>
+    <h1 class='title'>Uasthree Api Document</h1>
+
+    <div class='list'>
+      <strong class='no_print no_opacity about'>* 被勾选的内容将被打印</strong>
+
+      <ul>
+        <% @documents.each do |controller| %>
+          <li>
+            <input type='checkbox' class='no_print no_opacity print_selector' checked=1 />
+            <a href='#<%= controller_identifer(controller[:klass]) %>'><%= controller[:about] %></a>
+
+            <ul class='ul-controller'>
+              <% controller[:actions].each do |action| %>
+                <li>
+                  <input type='checkbox' class='no_print no_opacity print_selector' checked=1 />
+                  <a href='#<%= action_identifer(controller[:klass], action[:name]) %>'>
+                    <%= action[:desc] %>
+                  </a>
+                </li>
+              <% end %>
+            </ul>
+
+          </li>
+        <% end %>
+      </ul>
+    </div>
+
+    <% @documents.each do |controller| %>
+      <div class='controller' id='<%= controller_identifer(controller[:klass]) %>'>
+        <h2 class='controller-title'><%= controller[:about] %></h2>
+        
+        <% controller[:actions].each_with_index do |action, i| %>
+          <div class='action action-<%= i % 2 == 0 ? 'even' : 'odd' %>'
+              id='<%= action_identifer(controller[:klass], action[:name]) %>'>
+
+            <strong>功能说明</strong>
+            <p class='about'><%= action[:desc] %></p>
+
+            <strong>请求地址</strong>
+            <p class='about'><%= action[:path] %></p>
+
+            <strong>请求方法</strong>
+            <p class='about'><%= action[:method] %></p>
+
+            <strong>参数说明</strong>
+            <table class='table table-bordered table-striped'>
+              <thead>
+                <th>参数名</th>
+                <th>参数类型</th>
+                <th>描述</th>
+              </thead>
+
+              <tbody>
+                <% action['Params'].each do |param| %>
+                  <% format_param(param) %>
+
+                  <tr>
+                    <% [:name, :type].each do |key| %>
+                      <td><%= param[key] %></td>
+                    <% end %>
+
+                    <td>
+                      <%= param[:val] %>
+                      
+                      <% if param[:children] %>
+                        <% param[:children].each do |cp| %>
+                          <p style='padding-left: <%= (cp[:level] - 1) * 20 %>px'><%= cp[:desc] %></p>
+                        <% end %>
+                      <% end %>
+                    </td>
+                    
+                  </tr>
+                <% end %>
+              </tbody>
+            </table>
+
+            <strong>正常返回信息</strong>
+            <table class='table table-bordered table-striped'>
+              <thead>
+                <th>参数名</th>
+                <th>参数类型</th>
+                <th>描述</th>
+              </thead>
+
+              <tbody>
+                <% (action['Return'] || []).each do |param| %>
+                  <% format_error_param(param) %>
+
+                  <tr>
+                    <% [:name, :type, :val].each do |key| %>
+                      <td><%= param[key] %></td>
+                    <% end %>
+                  </tr>
+                <% end %>
+              </tbody>
+            </table>
+
+            <strong>出错误时信息</strong>
+            <p class='about'>
+              出错时response.status 为 400.
+
+              <table class='table table-bordered table-striped'>
+                <thead>
+                  <th>参数名</th>
+                  <th>参数类型</th>
+                  <th>描述</th>
+                </thead>
+
+                <tbody>
+                  <tr>
+                    <td>error</td>
+                    <td>String</td>
+                    <td>错误标识</td>
+                  </tr>
+
+                  <tr>
+                    <td>error_description</td>
+                    <td>String</td>
+                    <td>错误具体描述</td>
+                  </tr>
+                </tbody>
+              </table>
+              
+            </p>
+
+            <br /><hr />
+          </div>
+        <% end %>
+
+      </div>
+    <% end %>
+  </body>
+</html>

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: api_doc_generation
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
 platform: ruby
 authors:
 - jiangzhi.xie
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-07-15 00:00:00.000000000 Z
+date: 2013-07-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -57,6 +57,7 @@ files:
 - lib/rake/api_doc_generation.rb
 - lib/rake/tasks/api_doc.rake
 - templates/doc.html.erb
+- templates/doc_detailed.html.erb
 homepage: ''
 licenses:
 - MIT