API Blueprint

API Blueprint

API Blueprint 是一套 API 描述标准，和 Markdown 一样，属于一种标记语言，可以把标记文稿转换成漂亮的接口文档。

Aglio

将API Blueprint文件转换成html文件

aglio -i foo.md -o bar.html

Drafter

将API Blueprint文件转换成json文件

drafter api_blueprint.md -t ast -f json -o out.json

Nodejs

通过nodejs脚本将 API Blueprint json文件转化为HARs json

node snippet.js ./api.json /api-blueprint

snippet.js 主要是解析api.json文件，把它拆分成多个har json,每个har json对应一个接口。
该命令会在api-blueprint目录下生成多个har json文件，具体文件名由snippet.js定义。

apiembed

下载apiembed源码，启动apiembed服务:

## 正常启动
PORT=7777 node server.js

## 后台启动apiembed
sudo PORT=7777 nohup node server.js > logs/api.out 2>&1 &

将HAR文件转换成各种客户端代码片段

http://your.apiembed.com/?
source=http://yourhost/apib/hars/gists--id--PATCH.json&
targets=shell:curl,node:unirest,java:unirest,php:curl,objc:nsurlsession

Drakov

通过该命令可以生成API的mock测试接口，方便客户端测试。这样后端和客户端的开发就互不影响了。

drakov -f ./hello.md -p 3000

drakov -f ./hello.md -p 3000 --stealthmode
不输出日志

drakov -f ./hello.md -p 3000 --stealthmode --public
公开API，使得客户端可以通过IP访问，没有--public参数则只能通过localhost访问

nohup drakov -f "/opt/api-blueprint/*.apib" --public --watch > /dev/null 2>&1
后台运行,监控文件更新，重启服务,测试发现如果api被调用过后，再修改md文件则不会重启服务。

(nohup drakov -f  "/tmp/apiblueprint/*.md" --public --watch >/dev/null 2>&1 &)
以上命令可能无法后台运行drakov,则需使用该命令，即在末尾加上&并且用括号括起来。

setsid drakov -f  "/tmp/apiblueprint/*.md" --public --watch >/dev/null 2>&1 &
这样也行。

总体步骤

链接

• API Blueprint官网
• API Blueprint Tools
• 使用 API-Blueprint 编写 API 文档
• https://nodejs.org
• https://github.com/danielgtaylor/aglio
• https://apiembed.com
• https://github.com/apiaryio/drafter
• https://github.com/Aconex/drakov