Project

meta-api

0.01
The project is in a healthy, maintained state
一个 Web API 框架,该框架采用定义元信息的方式编写 API,并同步生成 API 文档
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Runtime

 Project Readme

Meta 框架

Meta 框架是一个用于开发 Web API 的后端框架,采用 Ruby 语言编写。正如它的名字,它是用定义“元”信息的方式实现 API,同时生成一份符合 Open API 规格的接口文档。

有关框架名称的由来,阅读框架的名称由来

脚手架

可直接使用我的脚手架项目上手体验:

$ git clone https://github.com/yetrun/web-frame-example.git

安装

在 Gemfile 中添加:

gem 'meta-api', '~> 0.2.0'

然后在 Ruby 代码中引用:

require 'meta/api'

或者可嵌入到 Rails 项目中使用,参考为 Rails 项目带来参数验证效果

快速一览

定义 API

通过继承 Meta::Application 来定义一个 API 模块。(PS:以下示例的运行依赖 ActiveRecord

class NotesAPI < Meta::Application
  get '/notes' do
    title '查看笔记列表'
    status 200 do
      expose :notes, type: 'array', ref: NoteEntity
    end
    action do
      render :notes, Note.all
    end
  end

  post '/notes' do
    title '创建新的笔记'
    params do
      param :note, type: 'object', ref: NoteEntity
    end
    status 201 do
      expose :note, type: 'object', ref: NoteEntity.lock_scope('full')
    end
    action do
      note = Note.create!(params[:note])
      response.status = 201
      render :note, note
    end
  end

  get '/notes/:id' do
    title '查看笔记'
    params do
      param :id, type: 'integer'
    end
    status 200 do
      expose :note, type: 'object', ref: NoteEntity.lock_scope('full')
    end
    action do
      note = Note.find(params[:id])
      render :note, note, scope: 'full'
    end
  end

  put '/notes/:id' do
    title '更新笔记'
    params do
      param :note, type: 'object', ref: NoteEntity
    end
    status 200 do
      expose :note, type: 'object', ref: NoteEntity.lock_scope('full')
    end
    action do
      note = Note.find(params[:id])
      note.update!(params[:note])
      render :note, note, scope: 'full'
    end
  end

  delete '/notes/:id' do
    title '删除笔记'
    status 204
    action do
      note = Note.find(params[:id])
      note.destroy!
      response.status = 204
    end
  end
end

定义实体

以上示例看到有用到 NoteEntity,它是一个预先定义的实体:

class NoteEntity < Meta::Entity
  property :id, type: 'integer', param: false # 不作为参数传递
  property :title, type: 'string'
  property :content, type: 'string', render: { scope: 'full' } # 列表页接口不返回此字段
end

生成 API 文档

通过主动调用以下的方法可以生成 Open API 的规格文档:

NotesAPI.to_swagger_doc

该 Open API 文档是 JSON 格式,可以在 Swagger UI 下预览效果。如果也不乐意自己搭建 Swagger UI,可以直接使用在线的:

http://openapi.yet.run/playground

将模块挂载在 Rack 下运行

API 模块同时也是一个 Rack 中间件,它可以挂载在 Rack 下运行。假设以上文件分别位于 notes_api.rbnote_entity.rb,在项目下新建文件 config.ru,并写入:

require 'meta/api'
require_relative 'notes_api'
require_relative 'note_entity'

# 将文档挂载到 /api_spec 锚点下
map '/api_spec' do
  run ->(env) { 
    [200, { 'CONTENT_TYPE' => 'application/json' }, [JSON.generate(NotesAPI.to_swagger_doc)]]
    }
end

# 启动 NotesAPI 中定义的接口
run NotesAPI

然后执行命令:bundle exec rackup,接口即可启动。

文档

支持

你可以通过以下途径获得支持:

  1. 通过 GitHub 提交 ISSUE
  2. 通过 QQ 群(489579810)获得实时答疑
  3. 对本项目提交 Pull Request

License

LGPL-2.1