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

发表于 分类于

Web 应用程序，由前端和后端两个部分构成。以前在传统的网站中，前端只需配合后端开发模板、美化样式以及用 Ajax 和后端交互

随着现在的发展趋势，前端设备层出不穷，网络客户端变的愈来愈复杂，不仅有桌面 web 端，移动端 web 端，还有 iOS、Android 这位大佬，另外对应 iPad 的版本也跑不掉。因此必须有一套统一的机制，方便不同的前端设备与后端进行交互，RESTful API 应运而生！

REST 的全称是 Representational State Transfer，即表述性无状态传输。它是一种设计风格，而不是标准，一般是基于 HTTP，因为本身 HTTP 也是无状态的，无需 session。分工的时候，后端只需输出接口（通常是 json 格式），响应客户端请求，而前端则负责渲染视图，处理业务逻辑。前后端只通过 API 来交互，大大的降低了耦合性

Markdown 和 API blueprint

以前我们写文档一般都是用 Markdown（到现在看见用 word 写文档的真的是泪牛满面（ ＴДＴ）），这是一种用来写作的轻量级标记语言（真的比 HTML 简单多了）。Markdown 可以随心所欲的导出多种格式，比如 HTML 和 PDF 等，而且很多网站也都直接支持 Markdown

之所以用 Markdown 来写文档，原因有二：其一是如上面提到的，优雅轻便，非常灵活；其二便是方便管理，因为是纯文本的，可以用 Git 做版本控制和多人协作，团队每个人都可以参与进来，而且每个改动都被记录在历史，这对有时因为特殊原因要退回到某个 API 版本的时候特别管用

而 API blueprint，它其实就是基于 Markdown 的拓展，向下兼容 Markdown，有以下特点：

  • 采用 Markdown 格式撰写，容易上手
  • 只定义规则和结构，不负责渲染，渲染由插件负责
  • 有非常多的插件，可以生成漂亮的 HTML 文档 或是 作为 Mock Server 运行

以下是一个简单的示例，具体用法可以参考官方文档：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# API的名字
API的描述

## Resource的名字 [/uri/to/resouce/{id}]
Resource的描述

### Action的名字，后面跟Type [GET]
Action的描述，下面是Request与Response的示例

+ Response 200

    + Headers

        Content-Type: application/json

    + Body

        {
            "id": 1
            "name": "some one"
        }

用 API blueprint 生成静态 HTML 文档

首先安装 aglio（依赖于 Node.js）：

1
npm install -g aglio

以下命令分别为生成静态 HTML 和开启一个本地实时预览服务：

1
2
3
4
# Default theme
aglio -i input.apib -o output.html
# Run a live preview server on http://localhost:3000/
aglio -i input.apib -s

渲染生成的 HTML，是不是很棒：

将 API blueprint 作为本地 Mock 服务

作为一枚前端开发，最让我头疼的就是和后端对接口。一般等后台写好接口后，连同文档和 API 一同丢给前端。这里有两个问题，一个是前端等待的时间太长，二个是 API 是后端写的，好不好用他可不管，到时候前端用的不爽，要改起来也是一番功夫（我见过把数据库字段直接输出给前端的，丢一份数据词典，看不懂的自己查（ ＴДＴ））

怎么解决这个问题呢，最好能建立一个标准的 workflow：确定产品原型之后，前后端共同确定第一版 API，之后前端可以立刻根据这份 API 模拟数据进行开发，后端根据 API 文档开发接口。后台 API 一旦发生改动，立即反应在 API 文档上，因为文档就是模拟数据的数据来源，这样前端的模拟数据也可以立即得到更新，按这个流程迭代下去，直至项目完成

那么，如何将文档作为 Mock Server 启动呢？其实非常简单，只要安装 api-mock  ，然后运行  api-mock input.apib -p 2999   就 ok 了

结语

上面介绍的只是工具，文档的意义在于减少沟通成本，让大家沟通起来更舒服，但若团队成员沟通意愿并不强烈，也没兴趣接受新的工作流程，即使这套文档系统再完美，也是白瞎