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

ruby

此文属于纯技术文章, 适合于 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

非常好理解,

继承了 Lina::ApplicatonController
使用 define_action 来定义, 路由照旧编写即可.

其中, define_action 第二个参数是一个 Hash, 必填的 keys: name, params, return.

如果你比较懂 Rails 内部, 就估计猜到我是如何实现的 APIDOC 自动生成与校验了. 留着下一篇写.

总结

这不是一篇完整的介绍 Lina 的内容, 主要目的是引出 Lina, 简单解释使用方法, 其项目主页在这里: http://linarb.org

另外, 我在 Ruby China 发起了发布说明: https://ruby-china.org/topics/24369

如果对你有帮助, 希望可以关注与分享, 谢谢你.

发表于 2015.02.27

二维码

Haley • 2017-07-04 16:29

赞我就是用的你的wblog 很不错

李亚飞 • 2015-04-05 09:55

@红红我一直在深圳.

红红 • 2015-04-04 11:14

你好，有来深圳可以交个朋友啊，我也程序员

cping • 2015-03-06 14:57

偶然经过贵站，盼望回访，xrpmoon.com/blog