api_doc_generation 0.0.5 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5dd65a3e0535829684cdead694989b6925fc4dc8
-  data.tar.gz: bed4b14919575ffd572bf54cb505ecad836a5c9a
+  metadata.gz: efc63e80bddcc349ab44b58451186d2a8cfbad04
+  data.tar.gz: e20a6e3d6621ea10514d813512ef744225556a1d
 SHA512:
-  metadata.gz: 049c508ad6dfacf37e953a0150cd805046edea284e31c71636de103aa4172b56f456412c1764588cb9bc73a3b51aece45948c24281a9939c28c000928ff872bb
-  data.tar.gz: 550ae99b642a1bc4558c0e72f13a14eff8ab04197a729110c822c5ff21874fffcfb792a45d0ee92c9b24a76aac361a3c6161a22e164ae8cea36fb46f1d351cbf
+  metadata.gz: 21741fec7a85800ac87c17968e6800fe12a89b1d01e5aefb70bdd97173189006fb751cd6e6ad110c28e0da984c0f2dbfeecb4143457eccb26452a3a024f7777f
+  data.tar.gz: 41d826effb4a3f52517c2d5193e76e6bcc36a7b59bb8ac9f8cffc84c365f988291631ffaa7e11d513adda0e31c7aeeadb8740b52e178c85994c8a8df0d36e5e6

data/README.md

@@ -20,6 +20,40 @@ Or install it yourself as:
 
 `rake doc:api [CODES_PATH=app/controllers/api]`
 
+__代码注释格式:__
+
+```
+  class Api::UsersController < class Api::BaseController
+    # 取得所有用户
+    # 
+    # Params:
+    #   page: [Integer] 页数
+    #   perpage: [Integer] 每页数量
+    # Return:
+    #   count: [Integer] 数据总条数
+    #   items: [Array] 当前页数据的数组
+    def list
+      # ...
+    end
+
+    # (api说明)取得一个用户的信息
+    # 
+    # Params:
+    #   user_id: [String] 用户的id
+    # Return:
+    #   name: [String] xxx
+    # Error:
+    #   info: [String] 自己定义的错误信息
+    #   other: [String] 如果不设置的，将生成默认的
+    def show
+      # ...
+    end
+  end
+```
+
+上面已经给出了api说明，参数，返回，错误信息,而api地址和请求方法将会自动从Rails中查找出来
+
+
 ## Contributing
 
 1. Fork it

data/lib/api_doc_generation/version.rb

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

data/lib/api_doc_generation/view_helper.rb

@@ -54,7 +54,7 @@ module ApiDocGeneration; class ViewHelper
   end
 
 
-  def format_error_param(param)
+  def format_response_param(param)
     return unless param[:val].to_s =~ /^\s*$/
 
     case param[:name]

data/templates/doc_detailed.html.erb

@@ -108,16 +108,16 @@
           <div class='action action-<%= i % 2 == 0 ? 'even' : 'odd' %>'
               id='<%= action_identifer(controller[:klass], action[:name]) %>'>
 
-            <strong>功能说明</strong>
-            <p class='about'><%= action[:desc] %></p>
+            <h4>功能说明</h4>
+            <p class='about text-info'><%= action[:desc] %></p>
 
-            <strong>请求地址</strong>
-            <p class='about'><%= action[:path] %></p>
+            <h4>请求地址</h4>
+            <p class='about text-info'><%= action[:path] %></p>
 
-            <strong>请求方法</strong>
-            <p class='about'><%= action[:method] %></p>
+            <h4>请求方法</h4>
+            <p class='about text-info'><%= action[:method] %></p>
 
-            <strong>参数说明</strong>
+            <h4>参数说明</h4>
             <table class='table table-bordered table-striped'>
               <thead>
                 <th>参数名</th>
@@ -149,7 +149,8 @@
               </tbody>
             </table>
 
-            <strong>正常返回信息</strong>
+            <h4>正常返回信息</h4>
+            <p class='about text-info'>正常完成时response.status 为 200.</p>
             <table class='table table-bordered table-striped'>
               <thead>
                 <th>参数名</th>
@@ -159,7 +160,7 @@
 
               <tbody>
                 <% (action['Return'] || []).each do |param| %>
-                  <% format_error_param(param) %>
+                  <% format_response_param(param) %>
 
                   <tr>
                     <% [:name, :type, :val].each do |key| %>
@@ -170,18 +171,27 @@
               </tbody>
             </table>
 
-            <strong>出错误时信息</strong>
-            <p class='about'>
-              出错时response.status 为 400.
+            <h4>出错误时信息</h4>
+            <p class='about text-info'>出错时response.status 为 400.</p>
+            <table class='table table-bordered table-striped'>
+              <thead>
+                <th>参数名</th>
+                <th>参数类型</th>
+                <th>描述</th>
+              </thead>
 
-              <table class='table table-bordered table-striped'>
-                <thead>
-                  <th>参数名</th>
-                  <th>参数类型</th>
-                  <th>描述</th>
-                </thead>
+              <tbody>
+                <% if action['Error'] %>
+                  <% action['Error'].each do |param| %>
+                    <% format_response_param(param) %>
 
-                <tbody>
+                    <tr>
+                      <% [:name, :type, :val].each do |key| %>
+                        <td><%= param[key] %></td>
+                      <% end %>
+                    </tr>
+                  <% end %>
+                <% else %>
                   <tr>
                     <td>error</td>
                     <td>String</td>
@@ -193,10 +203,9 @@
                     <td>String</td>
                     <td>错误具体描述</td>
                   </tr>
-                </tbody>
-              </table>
-              
-            </p>
+                <% end %>
+              </tbody>
+            </table>
 
             <br /><hr />
           </div>

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: api_doc_generation
 version: !ruby/object:Gem::Version
-  version: 0.0.5
+  version: 0.0.6
 platform: ruby
 authors:
 - jiangzhi.xie