转载

刚刚发布了一个基于 Rails 的 RESTful API 框架 Lina

此文属于纯技术文章, 适合于 Ruby 开发者查阅.

名字源由

Lina 是 DOTA 中秀逗魔导师的名字, 因为技能非常霸气, 常常超神, 所以这个项目就命名为 Lina.

Lina 是一个基于 Rails 的 RESTful 的 API 框架, 我希望它能像真正的 "Lina" 那样给予项目一种势如破竹的感觉.

项目主页: http://linarb.org

为什么造一个新轮子

各种语言都有一套写 JSON API 的框架, 却没有一种自动生成 APIDOC的. 尤其是 Ruby 界, 甚至还没有我使用的非常非常顺手的.

反而, 本不是为 RESTful API 而生的 Rails, 借助 jbuider 反而用的不错, 却缺乏了很重要的东西:

APIDOC
一套最佳实践
参数约束

于是, Lina 借助 Rails 与 JSONSchema 实现了这一目标:

自动生成 APIDOC
参数自校验
整合一套最佳实践( 基于 Rails )

安装使用

在 Rails 项目的 Gemfile 中添加

#  Gemfile gem 'lina'

bundle install 之后, 安装

$ rails g lina:install

# 生成对应的 API $ rails g lina:api posts index

APIDOC 自动生成

Lina 会自动将 APIDOC 生成出来, 默认访问地址位于: http://localhost:3000/apidoc

开发流程

Lina 下开发模式几乎等同于原生 Rails. 除了:

控制器定制
默认 format 已经被设置为 json

一个完整的 API 控制器如下:

class Api::PostsController < Lina::ApplicationController   # def index   define_action :index, {     name: '获取所有文章',     description: '这个接口用来获取所有文章, 参数及返回值请见下文',     params: {       properties: {         created_order_by: {           enum: [ :asc, :desc ],           default: 'desc',           description: '按创建时间正序或倒序排'         }       }     },     return: {       type: 'array',       items: {         type: 'object',         required: [:id, :name, :created_at],         properties: {           id: {             type: 'integer',             description: '文章ID',           },           name: {             type: 'string',             description: '文章标题',           },           created_at: {             type: 'string',             description: '创建时间, 格好的字符串'           }         }       }     }   } do     @posts = Post.order(created_at: params[:created_order_by].to_sym)   end    # def show   define_action :show, {     name: '获取某一篇文章的内容',     description: '',     params: {       type: 'object',       required: [:id],       properties: {         id: {           type: 'string',         }       }     },     return: {       type: 'object',       description: '返回文章详情',       required: [:id, :name, :content, :created_at],       properties: {         id: { type: 'integer' },         name: { type: 'string' },         content: { type: 'string' },         created_at: { type: 'string' },       }     }   } do     @post = Post.find(params[:id])   end end