lina 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e6f1263ff2802b1578fcae3f1f232e132adaef18
-  data.tar.gz: 08ef794c256ecc46fc922485c706b88bb3f0b5cd
+  metadata.gz: 42f21ae8ee02bcd29bc7d4b5fcf92f00473db66f
+  data.tar.gz: 524f10fe12b14452afcdaa4e3ee75e94ebe77c56
 SHA512:
-  metadata.gz: 276dace144d2887e604e311abfc8665b318b4c9861987d5277995c52a726e307361d62b24fd2ee27edfb7688d68319cab09309e4be4d6c4df768911a1ff128d0
-  data.tar.gz: 922061bff3767fe1c33c326a9e5ace5040871e9a429405b8e99e68a623c062212e2791832b0fe6d205be8855c0fb650d5b06571b3e8a17b8d12a070d51f49a37
+  metadata.gz: cec4c791a427e084e15a3a95e6863acbadd652cb5842c73fc47ea782e2899c089eff24e057ed0ccdccaa31a731f6d79f3db576879be80095c7aca084f0163afa
+  data.tar.gz: 877440440b7116f07894120ba7c2ab5c90cd2a5a6338bc0ab430055fecdf7f488d3eae4865bf51c65d5c6b7c698552e6fb613c26d22f5f63745ba2228426d4d2

data/README.md

@@ -1,10 +1,20 @@
 ![lina logo](lina-logo.png)
 
+[![Gem Version](https://badge.fury.io/rb/lina.svg)](http://badge.fury.io/rb/lina)
+[![license](http://img.shields.io/badge/license-MIT-red.svg?style=flat)](MIT-LICENSE)
 [![Build Status](https://travis-ci.org/windy/lina.png?branch=master)](https://travis-ci.org/windy/lina)
+[![Dependency Status](https://gemnasium.com/windy/lina.svg)](https://gemnasium.com/windy/lina)
 
 Rails 开发者零成本上手的 Restful API 框架.
 
-Lina 是基于 `Ruby on Rails`, [JSON Schema](http://json-schema.org), `jbuilder` 的 API 开发框架, 具备自动生成 API 文档, 自动校验入口, 自校验返回值参数等功能.
+Lina 是基于 `Ruby on Rails`, [JSON Schema](http://json-schema.org), `jbuilder` 的 API 开发框架, 整合 Ruby on Rails 开发 API 的最佳实践, 并添加 API 文档, 校验等必备功能.
+
+它的特点:
+
+* Rails 开发者零成本上手
+* 自动生成 API 文档
+* 自动校验入口参数
+* 自动校验返回值参数
 
 与 `Ruby on Rails` 几乎体验一致, 与 `grape` 相比, 更加易于上手.
 
@@ -25,17 +35,19 @@ $ rails g lina:install
 $ rails g lina:api posts index
 ```
 
-启动 Rails 后, 访问 http://localhost:3000/apidoc 得到你的 API 文档.
+启动 Rails 后, 访问 `http://localhost:3000/apidoc` 得到你的 API 文档.
 
-ps: 目前仅支持 `Rails 4.1+`, `Rails4.2`, 如果你有更低版本的支持需求, 请告诉我.
+ps: 目前仅支持 `Rails 4.1`, `Rails4.2`, 如果你有更低版本的支持需求, 请告诉我.
 
-Rails 新手 Lina 使用说明: [Rails 新手?](https://github.com/windy/lina/wiki)
+Rails 新手 Lina 使用说明: [Rails 新手?( TODO )](https://github.com/windy/lina/wiki)
+
+目前 Lina 最新版 0.0.2 已经基本完善.
 
 ##  使用方法
 
-### APIDOC
+### 自动 APIDOC
 
-`Lina` 会自动生成项目的 APIDOC, 供前端或客户端 APP 使用.
+`Lina` 会遍历所有 API 控制器, 自动生成项目的 APIDOC, 供前端或客户端 APP 使用.
 
 APIDOC 中包括:
 
@@ -67,9 +79,9 @@ api_for '/apidoc'
 
 	* `&block`: 控制器实际代码
 
-`Lina` 还提供了生成器 `rails g lina:api posts index show` 来快速生成代码.
+你可以使用 Lina API 生成器 `rails g lina:api posts index show` 来快速生成代码.
 
-`Lina` 控制器完全兼容 `Rails` 的控制器, `filter`, `render`, `params` 都与 `Rails` 完全一致.
+`Lina` 控制器逻辑代码完全兼容 `Rails` 的控制器, `filter`, `render`, `params` 都与 `Rails` 完全一致.
 
 ```ruby
 class UsersController < Lina::ApplicationController
@@ -169,7 +181,7 @@ bio: 非必填, string 类型.
 
 `return` 的写法与 `params` 一致.
 
-更全面的例子参考 [json-schema 官方例子](http://json-schema.org/examples.html)
+`json-schema` 非常强大与简洁, 可以很容易地写出既优雅又安全的代码, 更全面的例子参考 [json-schema 官方例子](http://json-schema.org/examples.html)
 
 ### JSON 生成
 
@@ -184,7 +196,7 @@ json.array! @posts do |post|
 end
 ```
 
-`Lina` 整合了 `jbuilder`, 请到这里查看更多写法: [jbuilder readme](https://github.com/rails/jbuilder)
+`Lina` 整合了 `jbuilder`, 请到这里查看更多写法: [Jbuilder README](https://github.com/rails/jbuilder)
 
 ### 路由与版本
 
@@ -193,7 +205,7 @@ end
 ```ruby
 Rails.application.routes.draw do
   resources :posts, only: [:index, :show]
-  
+
   resources :labels, only: [:index] do
     member do
       post :approve
@@ -202,7 +214,7 @@ Rails.application.routes.draw do
 end
 ```
 
-对外的 API 一定要用版本隔开, 如下:
+对外的 API 一定要用版本号隔开, 如下:
 
 ```ruby
 scope 'api/v1' do
@@ -222,13 +234,17 @@ end
 
 ### 权限与认证
 
-`Lina` 为了保持简洁, 并不提供这部分的支持.
+`Lina` 为了保持简洁, 并不提供这部分的支持, 但整合非常容易.
 
 * 权限管理, 推荐使用 [`cancancan`](https://github.com/CanCanCommunity/cancancan)
 * 认证, 推荐 `JWT`, 看看这里: [`ruby-jwt`](https://github.com/progrium/ruby-jwt)
 
 你可以像 `Rails` 一样使用 `Lina`.
 
+### CORS 跨域
+
+推荐使用 [`rake-cors`](https://github.com/cyu/rack-cors) 整合.
+
 ### 测试
 
 `Lina` 控制器的测试与 `Rails` 完全一致(事实上, lina:api 生成器会自动生成对应的测试代码 ), 在 Test::Unit 中, 一个例子如下
@@ -250,12 +266,15 @@ class DesksControllerTest < ActionController::TestCase
 end
 ```
 
-## 开发指南
+## 贡献指南
+
+Lina 做了以下几件事情:
 
 1. `define_action` 实际上会将 API 信息存入类实例变量中, APIDOC 通过 `Lina::ApplicationController` 的子类遍历, 依据这些信息显示的.
 2. 覆写 `send_action`, 提供入口检测与返回参数检测.
 3. 提供生成器 `lina:install`, `lina:api`.
 4. 添加 `api_for` 路由项.
+5. 一个强大的 APIDOC
 
 `lina` 使用了 [appraisals](https://github.com/thoughtbot/appraisal) 测试不同版本 Rails 的支持情况.
 

data/app/assets/javascripts/lina/abn_tree_directive.js

@@ -140,7 +140,7 @@
                 return b.uid = "" + Math.random();
               }
             });
-            console.log('UIDs are set.');
+            //console.log('UIDs are set.');
             for_each_branch(function(b) {
               var child, _i, _len, _ref, _results;
               if (angular.isArray(b.children)) {
@@ -241,7 +241,7 @@
             });
           }
           n = scope.treeData.length;
-          console.log('num root branches = ' + n);
+          //console.log('num root branches = ' + n);
           for_each_branch(function(b, level) {
             b.level = level;
             return b.expanded = b.level < expand_level;

data/app/assets/javascripts/lina/apidoc_controller.js

@@ -12,19 +12,4 @@ app.controller('ApidocController', [ '$scope', '$http', function($scope, $http){
     });
   }
 
-  $scope.isRequired = function(params, name){
-    return params.required.indexOf(name) != -1;
-  }
-
-  $scope.moreInfo = function(properties) {
-    properties = _.clone(properties);
-    ['type', 'description'].forEach(function(e){
-      delete properties[e];
-    })
-    var info = '';
-    _.keys(properties).forEach( function(k) {
-      info = info + k + ": " + properties[k] + "\n";
-    })
-    return info;
-  }
 }])

data/app/assets/javascripts/lina/json_parse_directive.js.erb

@@ -0,0 +1,119 @@
+app.factory('RecursionHelper', ['$compile', function($compile){
+  return {
+    /**
+     * Manually compiles the element, fixing the recursion loop.
+     * @param element
+     * @param [link] A post-link function, or an object with function(s) registered via pre and post properties.
+     * @returns An object containing the linking functions.
+     */
+    compile: function(element, link){
+      // Normalize the link parameter
+      if(angular.isFunction(link)){
+        link = { post: link };
+      }
+
+      // Break the recursion loop by removing the contents
+      var contents = element.contents().remove();
+      var compiledContents;
+      return {
+        pre: (link && link.pre) ? link.pre : null,
+/**
+ * Compiles and re-adds the contents
+ */
+          post: function(scope, element){
+            // Compile the contents
+            if(!compiledContents){
+              compiledContents = $compile(contents);
+            }
+            // Re-add the compiled contents to the element
+            compiledContents(scope, function(clone){
+              element.append(clone);
+            });
+
+            // Call the post-linking function, if any
+            if(link && link.post){
+              link.post.apply(null, arguments);
+            }
+          }
+      };
+    }
+  };
+}]);
+
+app.directive('jsonSchema', [ 'RecursionHelper', function(RecursionHelper){
+  return {
+    restrict: 'E',
+  scope: {
+    schema: '='
+  },
+  controller: ['$scope', function($scope){
+    $scope.isRequired = function(params, name){
+      return _.contains(params.required, name);
+    }
+
+    $scope.moreInfo = function(properties) {
+      properties = _.clone(properties);
+      ['type', 'description'].forEach(function(e){
+        delete properties[e];
+      })
+      var info = '';
+      _.keys(properties).forEach( function(k) {
+        info = info + k + ": " + properties[k] + "\n";
+      })
+      return info || '-';
+    }
+
+    $scope.isOneOf = function(){
+      return !! $scope.schema.oneOf;
+    }
+
+    $scope.isObject = function(){
+      return !! $scope.schema.properties;
+    }
+
+    $scope.isString = function(){
+      return $scope.schema.type == 'string';
+    }
+
+    $scope.isArray = function(){
+      return $scope.schema.type == 'array';
+    }
+
+    $scope.isNull = function(){
+      return $scope.schema.type == 'null';
+    }
+
+    $scope.isBoolean = function(){
+      return $scope.schema.type == 'boolean';
+    }
+
+    $scope.isEmpty = function(){
+      return _.isEmpty($scope.schema);
+    }
+
+    $scope.hasMoreInfo = function(value){
+      return value.type !== 'array'
+    }
+
+    // translate { '$ref': '#/definitions/xx' } to real hash
+    $scope.refInfo = function(ref_hash){
+      var ref = ref_hash['$ref'];
+      var refs = ref.split('/');
+      var res;
+      _.each(refs, function(ref){
+        if( ref === '#' ){
+          res = $scope.schema;
+        }else{
+          res = res[ref];
+        }
+      });
+      return res;
+    }
+  }],
+  compile: function(element){
+    return RecursionHelper.compile(element);
+  },
+  templateUrl: '<%= asset_path("templates/lina/schema.html") %>'
+  };
+
+}])

data/app/assets/javascripts/templates/lina/schema.html

@@ -0,0 +1,83 @@
+<div ng-if="isEmpty()">
+  <p class='blank'>
+  	No Data
+  </p>
+</div>
+<div ng-if="isOneOf()">
+  <p>
+    <div class="left">Type</div>
+    <div class="right">One type of these below</div>
+  </p>
+  <div ng-repeat='s in schema.oneOf'>
+    <div class="sub-json-schema">
+    	<json-schema schema='refInfo(s)'></json-schema>
+    </div>
+  </div>
+</div>
+<div ng-if="isString()">
+  <p>
+    <div class="left">Type</div>
+    <div class="right">String</div>
+  </p>
+  <p>
+    <div class="left">More Info</div>
+    <div class="right more-info ng-cloak">{{ moreInfo(schema) }}</div>
+  </p>
+</div>
+<div ng-if="isBoolean()">
+  <p>
+    <div class="left">Type</div>
+    <div class="right">Boolean</div>
+  </p>
+  <p>
+    <div class="left">More Info</div>
+    <div class="right more-info ng-cloak">{{ moreInfo(schema) }}</div>
+  </p>
+</div>
+<div ng-if="isNull()">
+  <p>
+    <div class="left">Type</div>
+    <div class="right">Null</div>
+  </p>
+</div>
+<div ng-if="isArray()">
+  <p>
+    <div class="left">Type</div>
+    <div class="right">Array</div>
+  </p>
+  <p>Items:</p>
+  <div class="sub-json-schema">
+    <json-schema schema='schema.items'></json-schema>
+  </div>
+</div>
+<div class='table-responsive' ng-if='isObject()'>
+	<table class='table ng-cloak'>
+	  <thead>
+	    <tr>
+	      <th width='20%'>Name</th>
+	      <th width='20%'>Type</th>
+	      <th width='25%'>More Info</th>
+	      <th>Description</th>
+	    </tr>
+	  </thead>
+	  <tbody>
+	    <tr ng-repeat='(key, value) in schema.properties'>
+	      <td><span>{{ key }}
+	        <span class="label label-primary" ng-show='isRequired(schema, key)'>must</span>
+	        <span class="label label-default" ng-hide='isRequired(schema, key)'>optional</span>
+	      </td>
+	      <td>{{ value.type }}</td>
+	      <td class='more-info' ng-if='hasMoreInfo(value)'>{{ moreInfo(value) }}</td>
+	      <td class='more-info-array' ng-if='! hasMoreInfo(value)'>
+          <div>
+          	Array Items:
+          </div>
+          <div class="sub-json-schema">
+            <json-schema schema='value.items'></json-schema>
+          </div>
+        </td>
+	      <td class='description'>{{ value.description }}</td>
+	    </tr>
+	  </tbody>
+	</table>
+</div>

data/app/assets/stylesheets/lina/{apidoc.css.scss → apidoc.scss}

@@ -2,6 +2,7 @@
   height: 100%;
   margin-right: 0;
   margin-left: 0;
+  font-weight: 300;
 
   .apidoc-title {
     border-bottom: 1px solid #eee;
@@ -12,13 +13,24 @@
     color: #999;
   }
 
+  .api-content-wrapper {
+    border-bottom: 4px solid #aaa;
+    margin-bottom: 30px;
+    padding-bottom: 10px;
+    &:last-child {
+      border: none;
+    }
+  }
+
   .more-info {
     white-space: pre;
   }
 
   .api-left-tree {
+    float: left;
+    width: 300px;
     height: 100%;
-    overflow-y: auto;
+    overflow: auto;
     background: #FAFAFA;
     border-right: 1px solid #eee;
     padding: 0;
@@ -26,11 +38,13 @@
     .nav-pills > li > a {
       border-radius: 0;
       padding: 6px;
+      white-space: nowrap;
     }
   }
 
   .api-contents {
-    padding-top: 10px;
+    margin-left: 300px;
+    padding: 10px;
     height: 100%;
     overflow-y: auto;
     font-size: 20px;
@@ -51,17 +65,18 @@
   .description {
     white-space: pre;
     color: #999;
-    font-size: 75%;
+    font-size: 85%;
   }
 
   .parameters-title, .return-title {
     margin-top: 28px;
     font-size: 28px;
+    font-weight: 400;
   }
 
   .table-wrapper {
     background: #E8F4FF;
-    padding: 10px 20px 20px;
+    padding: 10px;
     margin-bottom: 30px;
   }
 
@@ -73,9 +88,37 @@
 
   .table > thead > tr > th {
     border: none;
+    font-weight: 400;
   }
 
   .table > tbody > tr > td {
     border: none;
   }
+
+  .table > tbody > tr > td.description {
+    font-size: 90%;
+  }
+
+  .left {
+    display: inline-block;
+    width: 200px;
+  }
+
+  .right {
+    display: inline-block;
+  }
+
+  .sub-json-schema {
+    font-size: 85%;
+    margin-top: 20px;
+    margin-left: 20px;
+    margin-bottom: 20px;
+    border: 1px solid #cdd;
+    padding: 10px;
+  }
+
+  .blank {
+    color: #aaa;
+    margin-bottom: 0;
+  }
 }

data/app/views/lina/apidoc/index.html.erb

@@ -1,66 +1,27 @@
-<div class="row apidoc-page" ng-controller='ApidocController' ng-init="setData('<%= lina.data_path %>')">
+<div class="apidoc-page" ng-controller='ApidocController' ng-init="setData('<%= lina.data_path %>')">
 
-	<div class="col-md-3 api-left-tree">
+	<div class="api-left-tree">
 		<h4 class='apidoc-title'>APIDOC</h4>
     <abn-tree tree-data="my_data" tree-control="my_tree" on-select='showApi(branch)'></abn-tree>
 	</div>
-	<div class="col-md-9 api-contents">
+	<div class="api-contents ng-cloak">
     <ul class='list-unstyled'>
-      <li ng-repeat='api in currentApi'>
-      <div class='path'>
-        <span class='path-verb'> {{ api.verb }} </span>
-        <span class='path-path'> {{ api.path }} </span>
-      </div>
+      <li class='api-content-wrapper' ng-repeat='api in currentApi'>
+        <div class='path'>
+          <span class='path-verb'> {{ api.verb }} </span>
+          <span class='path-path'> {{ api.path }} </span>
+        </div>
         <div class="name">{{ api.schema.name }}</div>
         <p class='description'>{{ api.schema.description }}</p>
         <h4 class='parameters-title'>Parameter</h4>
         <div class="table-wrapper">
-        	<table class='table'>
-        	  <thead>
-        	    <tr>
-        	      <th width='20%'>Name</th>
-        	      <th width='20%'>Type</th>
-        	      <th width='25%'>More Info</th>
-        	      <th>Description</th>
-        	    </tr>
-        	  </thead>
-        	  <tbody>
-        	    <tr ng-repeat='(key, value) in api.schema.params.properties'>
-        	      <td><span>{{ key }}
-        	        <span class="label label-primary" ng-show='isRequired(api.schema.params, key)'>must</span>
-        	        <span class="label label-default" ng-hide='isRequired(api.schema.params, key)'>optional</span>
-        	      </td>
-        	      <td>{{ value.type }}</td>
-        	      <td class='more-info'>{{ moreInfo(value) }}</td>
-        	      <td>{{ value.description }}</td>
-        	    </tr>
-        	  </tbody>
-          </table>
+          <json-schema schema='api.schema.params'></json-schema>
         </div><!-- .table-wrapper -->
 
         <h4 class='return-title'>Return</h4>
+        <p class='description'>{{ api.schema.return.description }}</p>
         <div class="table-wrapper">
-        	<table class='table'>
-        	  <thead>
-        	    <tr>
-        	      <th width='20%'>Name</th>
-        	      <th width='20%'>Type</th>
-        	      <th width='25%'>More Info</th>
-        	      <th>Description</th>
-        	    </tr>
-        	  </thead>
-        	  <tbody>
-        	    <tr ng-repeat='(key, value) in api.schema.return.properties'>
-        	      <td><span>{{ key }}
-        	        <span class="label label-primary" ng-show='isRequired(api.schema.return, key)'>must</span>
-        	        <span class="label label-default" ng-hide='isRequired(api.schema.return, key)'>optional</span>
-        	      </td>
-        	      <td>{{ value.type }}</td>
-        	      <td class='more-info'>{{ moreInfo(value) }}</td>
-        	      <td>{{ value.description }}</td>
-        	    </tr>
-        	  </tbody>
-        	</table>
+          <json-schema schema='api.schema.return'></json-schema>
         </div><!-- .table-wrapper -->
       </li>
     </ul>

data/lib/generators/lina/api/USAGE

@@ -0,0 +1,16 @@
+Description:
+    Creates API controller and action(s) to your application.
+
+Example:
+    rails generate lina:api Posts index show
+
+    This will create:
+        create  app/controllers/posts_controller.rb
+         route  get 'posts/show'
+         route  get 'posts/index'
+        invoke  test_unit
+        create    test/controllers/posts_controller_test.rb
+        invoke  jbuilder
+        create    app/views/posts
+        create    app/views/posts/index.json.jbuilder
+        create    app/views/posts/show.json.jbuilder

data/lib/generators/lina/api/api_generator.rb

@@ -0,0 +1,60 @@
+module Lina
+  module Generators
+    class ApiGenerator < Rails::Generators::NamedBase # :nodoc:
+      source_root File.expand_path("../templates", __FILE__)
+
+      argument :actions, type: :array, default: [], banner: "action1 action2"
+      check_class_collision suffix: "Controller"
+
+      def create_controller_files
+        template 'controller.rb', File.join('app/controllers', class_path, "#{file_name}_controller.rb")
+      end
+
+      def add_routes
+        actions.reverse.each do |action|
+          route generate_routing_code(action)
+        end
+      end
+
+      hook_for :test_framework, as: :controller
+
+      if Lina.generate_views
+        hook_for :view, default: true
+      end
+
+      private
+
+      # This method creates nested route entry for namespaced resources.
+      # For eg. rails g controller foo/bar/baz index
+      # Will generate -
+      # namespace :foo do
+      #   namespace :bar do
+      #     get 'baz/index'
+      #   end
+      # end
+      def generate_routing_code(action)
+        depth = regular_class_path.length
+        # Create 'namespace' ladder
+        # namespace :foo do
+        #   namespace :bar do
+        namespace_ladder = regular_class_path.each_with_index.map do |ns, i|
+          indent("namespace :#{ns} do\n", i * 2)
+        end.join
+
+        # Create route
+        #     get 'baz/index'
+        route = indent(%{get '#{file_name}/#{action}'\n}, depth * 2)
+
+        # Create `end` ladder
+        #   end
+        # end
+        end_ladder = (1..depth).reverse_each.map do |i|
+          indent("end\n", i * 2)
+        end.join
+
+        # Combine the 3 parts to generate complete route entry
+        namespace_ladder + route + end_ladder
+      end
+    end
+  end
+end

data/lib/generators/{templates → lina/api/templates}/controller.rb

@@ -5,12 +5,12 @@ require_dependency "<%= namespaced_path %>/application_controller"
 <% module_namespacing do -%>
 class <%= class_name %>Controller < Lina::ApplicationController
 <% actions.each do |action| -%>
+  # def <%= action %>
   define_action :<%= action %>, {
     name: '<%= action %>',
     description: '',
     params: {
       type: 'object',
-      required: [],
       properties: {
       }
     },

data/lib/generators/lina/{install_generator.rb → install/install_generator.rb}

@@ -1,8 +1,10 @@
 module Lina
   module Generators
     class InstallGenerator < Rails::Generators::Base
-      source_root File.expand_path("../../templates", __FILE__)
+      source_root File.expand_path("../templates", __FILE__)
+
       desc "Create a lina initializer"
+
       def copy_initializer
         template "lina.rb", "config/initializers/lina.rb"
       end

data/lib/generators/lina/view/templates/view.json.jbuilder

@@ -0,0 +1,2 @@
+json.name '<%= class_name %>#<%= @action %>'
+json.path 'Find me in <%= @path %>'