API LEAF:基于测试生成API文档

前言

当下的web开发中，前后端分离的体制基本已经成型，这时候一份好的API文档对于前后端沟通来说是十分重要的桥梁。

但现实是，书写API文档对于后端开发人员来说一直是一件十分头疼的事情，虽然有着诸如Java Doc、Api Doc这样的工具，生成API文档依然需要后端人员手动填充大量的内容，而且生成的文档可维护性差，稍有修改就需要重新执行生成新的文件，或是依赖于某种语言和框架，不够通用...

综合长时间书写API文档的痛苦体验，一个全新的思路诞生了，那就是把文档生成这道工序从代码中剥离出来，使用测试来生成文档。

基于这样的思路，不洗碗工作室开发了使用测试来生成和管理API文档的工具一叶(Api Leaf)。

基于HTTP的接口测试

后端开发人员不可避免的需要对自己的接口发送模拟的HTTP请求，来测试结果。通常我们会使用POSTMAN这样的工具来进行测试。

实际上，一个成功的测试所包含的请求内容和响应内容，本身就可以作为文档的参考（很多文档里都会附有这样的请求和响应示范）。事实上，在我们团队早期的开发工作中，也经常利用POSTMAN测试后生成的COLLECTION来进行前后端的沟通，它大概是下面这样的：

但实际上这样生成的测试用例集合可读性非常差，而且不好维护和管理，于是我们又需要在测试完之后去手动的书写文档，再把测试用例复制进文档里当做示范...一个复杂的API文档就要书写很久，实在是打击后端开发人员的积极性。

基于测试结果提取API信息

仔细的分析一下，API文档中所包含的内容无非是请求和响应字段有哪些，分别是什么含义，实际上这些内容已经包含在测试的请求和响应体中了。

所以不妨来对这些信息进行一些抽象，请求和响应的数据一般都是JSON数据，前端在阅读文档时，真正关心的有以下的内容：

• 字段的名称，也就是json的key

• 字段值的类型，也就是json的value的type

• 字段值的描述，这是对字段更详细的一些说明，包括一些表单的验证规则等（并不是每个字段都必要的）

• 数据的结构，主要是对象或者是数组之间的嵌套关系

那么这些值是否都可以从一个完整的测试数据中提取出来呢，如果可以的话，把这些工作交给代码去生成，可就解放了后端人员的双手和心智。

答案是肯定的，我们把文档中的一项（表格中的一行）抽象成下面这样一个对象:

{

key:...

type:...

description�:...

}

通过按照层级遍历JSON对象的每一个属性很容易得到它，key自然是自动填充的，type可以根据代码推断，只有description需要人手工去填写，而这个字段还不是必要的...

剩下的问题是考虑遍历之后如何去保留对象之间的层级关系，比如下面这个JSON响应：

{

"code": 0,

"data": {

"problems": [

{

"id": 1001,

"title": "A+B（基本输入输出1）",

"difficulty": 2,

"source": "",

"submit": 3403,

"accepted": 1765,

"is_public": 1,

"created_at": "2014-01-17 00:18:19",

"updated_at": null,

"name": "basic",

"tags": [

{

"tag_title": "basic",

"tag_id": 1

}

]

}

],

"total_count": 576

}

}

最外层的对象中包含了code和data两个属性，data中又包含了一个名为problems的数组，problems中的每个对象又拥有诸多属性...

想要记录下结构其实也并不复杂，我们只需要记录下子属性的父属性就可以了。换句话说，你只要知道这个字段是隶属于哪个字段的，总能顺藤摸瓜一路摸清整个JSON的结构，就好像树这种数据结构的遍历一样。

使用代码进行简单的层级遍历和筛选，最终可以得到像下面这样的文档结构：

由于层级遍历的顺序，最终结果的排列顺序也是从最外层向最内层扩充的，具有很高的可读性。

最后我们需要对包含多个同样模型的对象数组做个筛选，只保留它的第一个元素就足以生成文档了。

整个测试的所有部分基本上都可以这样处理，包括请求头、query string、请求体、响应头、响应体，根据需要来进行组合，把所有测试的API集合在一起，最终就是一份完整的API文档了。

使用一叶生成文档

上述的思路已经在我们的测试用工具一叶中实现了。利用这个工具，书写API文档的时间已经被大大压缩，一个API的文档生成平均只需要几秒钟就可以解决了，现在让我们来看看如何使用这套工具。

创建项目

一叶的文档是根据项目生成的，因此在开始生成文档前你需要先创建自己的项目，登录注册后的主面板上可以看到你所创建的项目和参与的项目

进行测试

首先访问一叶的网站： 并注册登录，在右上角的下拉菜单中，选择“发起测试”后会跳转到下面这个页面：

这是使用JS和FETCH技术实现的在线的请求测试工具，使用起来的感觉和POSTMAN几乎一样。由于使用了和前端请求一样的FETCH方式，使用它进行测试你还可以检查到一些其他的bug，比如请求的跨域问题等等。

输入URL进行测试，填写好测试用的body和headers就可以发起请求，进行测试，收到响应后Response中将会显示请求的header和body。

生成文档

确定你测试的请求和响应没有异常之后，就可以立刻生成该API的文档，点击最下方的“生成文档”按钮就可以开始文档的生成了，这时候一叶会根据JSON的内容自动解析好文档项的结构，并以json的方式展示出来。

每个可能需要生成文档的部分都会被自动解析成这样的包含key,type,description三部分的结构，其中只有description字段需要手动填写（如果不需要也可以不填留空），对于不需要生成文档的部分可以在左上角取消勾选来忽略。

填写好必要的description字段后别忘了填写API的基本信息：所属的项目、名称、以及分类（GROUP），最后点击生成文档，该API的文档就完成了，这时候会显示如下的预览界面：

分享项目文档

最终一个项目文档的展示页面如下：

提供了非常多的辅助筛选、定位、排序功能，方便前端人员的查阅

生成文档后你需要把自己的项目文档发送给前端使用，这非常的简单，只要把查看文档的链接复制分享就可以了。

一个项目的文档将随着你的添加和更改自动变化，你不用再担心文档的维护问题，只要做好测试，其他的一切都是自动的了。

其他

文档的生成在较大型的公司中一般会使用根据框架专门编写的自动化测试和生成工具，但是对于中小型开发团队来说，开发这样的工具成本太高，代价太大，手工去书写又耗费时间，这时候就非常适合使用一叶这样的通用工具来生成和共享文档。

本项目目前代码开源在GitHub上，地址：https://github.com/MarkLux/ApiLeaf

基于PHP的Laravel框架开发，如果公司内部对API有保密需要，也完全可以在内部服务器中快速搭建一叶平台进行内部测试交流。

目前本项目已经经过一次内部测试，并且仍在持续开发中，欢迎广大开发者试用并提出宝贵意见。