使用Api-blueprint文档创建mock server

前后端配合开发的时候，常常会有这样一种需求：
“你接口定义好了吗？能不能先帮我起一个 Mock Server 先跑起来？”
那么，如何才能避免前后端开发在时间差上的无谓等待呢？api-blueprint，也许就是你想要的福音。

API Blueprint是一套API描述标准，和Markdown一样，属于一种标记语言，可以把标记文稿转换成漂亮的接口文档。还可以创建 mock server ，进行本地调试。

一、语法

只要用 markdown 写过东西, 基本很快就能掌握API Blueprint Language 语法。

• 官方 例子 ，一共也就 10 多个，耐心看完，心里就大概有数了；

• 语法规范；

• 官方 解释器 ，有了这个解析器，就可以很容易的扩展自己的相关工具了（比如代码生成等）

二、Mock server

• api-mock

• drakov

两者都可以根据 api-blueprint 的文档创建一个本地的 mock server 。

安装与使用都非常简单，只要选其中的一种安装即可，确保本地装有 node 环境：

$ node -v

如果能获取到版本号，如：

v6.5.0

就可以直接安装mock工具啦，如果不行的话自行Google一下安装一个呗。

2.1 工具一：安装api-mock

$ npm install -g api-mock

启动 mock server，方法中的 api.md 就是所需 server 的 api-blueprint 文档名

& api-mock ./api.md --port 3000

2.2 工具二：安装drakov

$ npm install -g drakov

启动 mock server，方法中的 api.md 就是所需 server 的 api-blueprint 文档名

$ drakov -f api.md -p 3000

三、生成静态 HTML

aglio 是一个可以根据 api-blueprint 文档生成静态 HTML 页面的工具。

aglio不是简单的 markdown 到 html 的转换, 而是可以生成类似 rdoc 这样的拥有特定格式风格的查询文档

3.1 安装

确保本地装有 node 环境：

$ npm install -g aglio

3.2 生成 HTML

$ aglio -i api.md -o api.html

四、本地调试

新建一个 statistics.md 文件, 输入如下内容:

FORMAT: 1A

# Example API

statistics

## 统计 [/statistics]

### 获取统计数据 [GET]

+ Response 200 (application/json)
{
            "success": true, 
            "err_code": "888888", 
            "err_msg": "错误说明",
            "data": [{
                "hour": "2016-10-31",
                "totalIncome": "1000.09",
                "totalRefund": "100.08",
                "incomeOrders": 70,
                "refundOrders": 10,
                "totalOrders": 80
            }]
 }   
 

4.1 生成HTML文档

$ aglio -i statistics.md -o statistics.html   

点击查看

4.2 创建 mock server

前面安装的mock工具是drakov，创建mock服务的命令行如下：

$ drakov -f ./statistics.md -p 3000

如果你安装的是api-mock：

$ api-mock ./statistics.md --port 3000

当所有的都弄完以后，就可以访问http://localhost:3000/statistics，发送网络请求获取数据，无需等待，前后端同步进行，nice。

参考文档

1. 使用 API-Blueprint 编写 API 文档

2. api blueprint

3. 用 API blueprint 生成优雅的 RESTful API 文档

4. API Blueprint Docker

5. API Blueprint

6. API Blueprint 指导手册

7. 用 API blueprint 生成优雅的 RESTful API 文档