前言

今天发现了一个很niubility的东西API Blueprint,先给出官网https://apiblueprint.org/。下面是官网给出的介绍:

API Blueprint. A powerful high-level API description language for web APIs.

这个可以干什么呢?按照API Blueprint的语法(类似markdown),我们可以利用生态链工具:

  1. 生成API接口文档
  2. 模拟接口在你没写任何代码之前
  3. 待研究…

对于1因为之前调研过Swagger等工具还是关注过一段时间写接口文档的事情,当时选取的方案就是Swagger,当时也觉的挺好用的,最后的接口文档也是可以真实返回数据的,但是问题呢就是写Swagger依赖的json文档是个问题,官方支持的语法是yaml(要是markdown多好啊),直接手动维护所有接口的json文档很X疼的啊,最后发现一个sosoapi的东东可以生成Swagger依赖的json文档,但是没开源啊!!!所以使用要是选型API Blueprint语法作为接口文档书写标准,的确是个不错的选择。

贴一下Swagger的官网http://swagger.io/

其次,API Blueprint最让我觉得厉害的就是我曾经幻想的:先制定接口数据结构,然后通过这个数据结构先模拟接口响应,之后客户端的同学和后端的同学就可并行的开发,客户端的同学再也不用等到后端的同学开发完毕再对接接口了,后端同学开发完毕无缝切换到真实代码上即可。

试用

  • 工具选用

看了生态链下眼花缭乱的工具,先选了个go开发的工具snowboard

  • 安装
1
2
3
4
5
6
7
8
// linux下安装,这里安装的是v0.5.0版
wget https://github.com/subosito/snowboard/releases/download/v0.5.0/snowboard-v0.5.0.linux-amd64.tar.gz
tar -zxvf snowboard-v0.5.0.linux-amd64.tar.gz
./snowboard -h

// mac下安装
$ brew tap subosito/packages
$ brew install snowboard
  • 编写第一个接口文档
  1. 新建一个.apib后缀的文件api.apib

推荐api-blueprint语法插件:language-api-blueprint 例如,Atom

  1. 编写接口文档
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// 示例
# API
## GET /v1/message
+ Response 200 (application/json)
{
"status":"OK",
"result":
{
"lists":[
{"id":666},
{"id":888}
],
"count":10
}
}
  1. 生成接口文档html页面
1
2
// 命令
./snowboard html -i api.apib -o api.html -s

访问 http://127.0.0.1:8088/
http://odcgj0xrb.bkt.clouddn.com/api-html.png

  1. 启用接口模拟
1
2
3
4
5
6
7
// 命令
./snowboard mock -i api.apib

// 返回
Mock server is ready. Use 127.0.0.1:8087
Available Routes:
GET 200 /v1/message

访问 http://127.0.0.1:8087/v1/message
http://odcgj0xrb.bkt.clouddn.com/api-json.png

结语

是不是很不错的东西,提高生产效率的利器啊,哈哈~ 我今天才知道………. 看它还有很多的工具,包含和Swagger结合使用的,后续慢慢研究,今天先过了个新鲜劲~

Easy PHP:一个极速轻量级的PHP全栈框架