API Blutprint: RESTful接口文档设计工具配置

我的GitHub博客：咖啡成瘾患者



爸爸是攻城狮！！嗷~~

目前主流web程序架构中，为了尽量降低前后端的耦合性，大多选择将前后端分离设计，前后端通过RESTful接口进行数据交互。这种设计方案的好处不用太多赘述，但需要项目在开发前编写一个具有较高可读性的接口设计文档，这样前后端在进行开发的时候就可以参考项目设计文档设计自己的模块，降低交流的成本。

作为一个自封的实验室攻城狮，编写设计文档一直都是一件让自己十分抓头发的事，不是编出来可读性差，就是花很多精力与时间磨一个设计文档，于是为了编写出更高质量的设计文档（其实主要动力是懒），一直在寻觅一个好用的RESTful接口文档设计工具。直到偶然发现了API Blueprint这款工具，甚合朕意~~

API Blueprint使用Markdown来编写API文档，然后可以直接生成一个漂亮的html页面，这样就可以专注于文档的内容，不用为了提高可读性而过多在排版上花费太多精力，简直是懒癌晚期程序员的福音！

下面上干货了，关于如何配置这个东西呢，其实简单应用的话并不复杂，一方面要配置一下一个好用的编辑环境，另一方面要把API Blueprint的解析环境配置好。主要的配置过程参考了Lulee007的文章：使用 API BluePrint 编写 RESTful 接口文档。

编辑环境的配置

Lulee007里主要介绍了atom的配置方法，atom插件功能更强大一些，同时atom的插件里还有一个叫做api-blueprint-preview的插件可以用来预览导出，习惯atom的孩纸可以用这个。

我个人用vscode比较多，其实API Blueprint就是用markdown来编写API文档，内容是服从markdown语法的，因此只要让vscode识别出*.apib文件（API Blueprint文件的后缀名），将这种类型的文件应用markdown语法高亮就可以了。vscode的插件库里有一款叫做API Blueprint Language的插件，安装好了之后就支持apib文件的高亮了。

但是vscode中貌似不可以使用预览功能来查看Blueprint的效果，不过没关系，aglio可以直接在本地启动一个server在浏览器里看效果。

aglio的配置

aglio是Blueprint的解析环境，是一个node.js编写的程序，安装之前需要先配置好node.js，直接使用npm安装就可以：

sudo npm install -g aglio

浏览器查看效果

对于一个apib文件，如果想看这个文件的效果，可以在终端里输入：

aglio -i testrestapi.apib -s

有时候可能需要root权限，出现permission deny的错误的时候加sudo运行就可以了。效果如下：

生成html

尽管应用aglio工具可以将apib文件转化为漂亮的浏览器页面，但是这样的方式显然是不便于流通的，并不是每个人电脑上都配置里aglio工具的，最好能把apib转为为可读性更高的html页面。aglio工具提供了这样的功能。在终端输入：

aglio -i testrestapi.apib -o testapi.html

即可生成一个名为testapi.html的网页文件。

API Blueprint的语法与高级功能

一个完整的 API BluePrint 文档要包括以下部分(带*为必须有)：

Metadata section 元数据部分*

API name & overview section API 名称和说明部分*

Resource group section 资源组部分

Resource section 资源部分*

Resource model section 资源模型部分

Schema section

Action section 动作部分*

Request section 请求*

Response section 相应*

URI parameters section 请求 URL 参数

Attributes section 属性部分

Headers section HTTP Headers 部分

Body section HTTP Body 部分*

元数据 Metadata

具体的语法规则可以看API Blueprint文档与Lulee007博客中的说明。关于样例方面，官方的github里有一个很全面的example文件夹，照着读一读语法就差不读了。Lulee007在自己的github上也放了一个样例，很全面的一个apib的文档，基本上大部分接口文档都可以照着这个改一改。

除此之外，aglio还支持很多不同的主题，比如生成三栏的页面：

sudo aglio -i testrestapi.apib --theme-template triple -o output.html

生成黑色主题的页面：

sudo aglio --theme-variables slate -i testrestapi.apib -o output.html

更详细的功能参数可以参考aglio的github。

参考

API Blueprint文档

使用 API BluePrint 编写 RESTful 接口文档 –Lulee007

aglio的github