ApiLeaf·多是史上最省事的文档生成工具

简介

我相信不少编写后台接口的同窗们都跟我同样，对于接口文档的编写头痛不已：编写文档费时、费力，实在是打击开发者的开发热情，尤为是在中小型项目的敏捷开发，每每编写文档花的时间比接口开发的时间还长。

对于大型项目和成熟团队，通常都会有成熟的接口自动化测试工具，集接口测试、自动构建和mock数据一体，可是中小型开发团队（好比学生组织）每每没有搭建相似平台的能力。

因而不少人索性不留文档了，但这又会增长先后端的沟通成本，下降整个团队的工做效率。

正所谓“懒，是人类进步的第一动力”，本着尽量减小文档编写工做的偷懒目的，我尝试开发了这款文档生成工具和管理平台：ApiLeaf，若是你也是小型团队中的后端开发者，也和我同样不喜欢写文档，就来看看它能不能帮到你吧！

核心思路

所谓API文档，无非是对于接口 请求 => 响应 这个过程的一个详细描述和说明，而对于后端开发者而言，这个流程正是咱们平常测试接口的过程，那么只要可以将这个测试过程记录并重放，附上一些必要的说明，不就能够做为文档使用了吗？

举个例子，咱们如今有一个计算 A + B 的接口，请求URL为http://localhost:8080/add，须要对它作一次测试，因而咱们POST过去下面的数据：

{
	"a": 1,
	"b": 2
}
复制代码

接着成功收到服务端的响应：

{
	"code": 0,
	"result": 3
}
复制代码

接口的测试完成了，让咱们看看从这个过程当中，均可以拿到哪些数据：

• 请求的URL
• 请求的方法Method
• 请求头Headers
• 请求体Body的结构
• 一个正确的请求示范

以及

• 响应头Headers
• 响应体Body的结构
• 一个正确的响应示范

根据这些内容已经彻底足够生成对应的接口的文档了，一般状况下只须要对Headers和Body中的各个字段添加一些基本的描述就能够生成一份至关详尽的文档.

ApiLeaf正是基于这样一个思路，只要你在ApiLeaf上进行接口的测试，它就能记录测试过程当中的请求和响应数据，而且自动构建文档的基础结构，大多数状况下你只须要补充一些基本描述（若是你使用了下文介绍的数据字典功能，甚至都不用填写描述），就能快速地生成文档。

文档自动生成示范

废话说了很多，不如来上手试试吧，首先访问ApiLeaf，注册并登录你的帐号，而后点击首页的主面板进入你的我的面板。

我的面板中提供了文档的管理界面，在开始尝试文档自动生成以前，咱们须要先创建一个项目。

在我建立的项目面板中，点击新建项目来建立一个项目，你只须要填写一下项目名和描述就能够了：

接下来点击右上角的下拉菜单，选择发起测试便可进入HTTP测试面板，你会看到一个相似POSTMAN的界面。

如今咱们来进行接口测试吧，以我本地的一个测试登陆接口为例，这个接口接收一个login_name和一个password，成功后返回登陆的用户基本模型，咱们补充好请求的URL和Body，而后就能够发送请求进行HTTP测试了：

Api Leaf使用fetch来发送这个请求，所以你能够用它来测试本地的接口，而且能够最大程度的模拟前端请求的真实环境，不过须要稍微注意一下跨域问题。

若是测试成功，你即可以在下方的Response面板中看到服务器所返回的响应内容了：

若是测试失败，没法获取响应，能够打开浏览器的控制台追踪fetch请求的异常缘由。

如今咱们就能够点击生成文档进入接口文档的编辑页面了

首先咱们须要补充一下接口的基本信息，选择该接口所属的项目(生成后这个接口的文档将自动纳入该项目的总文档中)，URL和METHOD已经自动填充好了，补充一下名称、描述便可。你还能够给接口填写一个组名，用于在整个项目中进行接口的分类管理，这在项目接口不少的时候仍是仍是很是有用的。

接下来咱们会看到不少的JSON编辑器，ApiLeaf会把从刚才的测试中拿到的数据分为如下7个部分，并自动填入到对应部分的编辑器中:

• API请求头部（Headers）
• API请求参数（QueryString）
• API请求体（Body）
• API请求示范
• API响应头（Headers）
• API响应体（Body）
• API响应示范

以刚才的测试为例，响应体编辑框中将会填入以下内容

[
	{
		"body_key": "code",
		"body_type": "integer",
		"body_description": ""
	},
	{
		"body_key": "user",
		"body_type": "object",
		"body_description": ""
	},
	{
		"body_key": "user.id",
		"body_type": "integer",
		"body_description": ""
	},
	{
		"body_key": "user.name",
		"body_type": "string",
		"body_description": ""
	},
	{
		"body_key": "user.sex",
		"body_type": "string",
		"body_description": ""
	},
	{
		"body_key": "user.age",
		"body_type": "integer",
		"body_description": ""
	}
]
复制代码

ApiLeaf会将响应JSON中全部的key都抽离，构建层级关系（以.分割）并自动推断他们的数据类型，你所须要作的只有检查body_type是否正确，而且补充body_description字段说明便可。

对于其余部分的内容，也会生成相似的JSON并填入对应的编辑器中，你只须要像作填空题同样将他们补充完整。对于不须要的部分，能够取消勾选，这样文档中就不会包含响应部分的内容，好比这个API中我只须要勾选请求体，响应体及其示范就足够了。

须要注意的是，编辑框中的内容必须是合法的JSON，而且对于每一个字段的key都有要求，因此请不要随便修改内含对象的结构，不然可能会引发错误（至于为何以JSON的方式填充，固然是由于这样就能够偷懒不用作界面了。。）

完成这些简单的填空题以后，文档就能够生成了，你会看到这个API文档的预览界面：

提供请求和响应两个标签页分别展现相应的说明。

至此，一个结构的文档生成就完成了，理想的状况下，测试+生成文档的过程不超过1分钟，仍是很是方便的。

若是你以为这样仍是麻烦，不想填这么多填空题，能够看看下面的数据字典部分，若是合理使用，你甚至能够不用填写任何内容就生成完整的文档！

数据字典与自动匹配

数据字典，是指在一个项目中频繁使用的基本数据结构，好比刚才测试项目中的User对象，做为用户数据的基本定义，可能在不少接口中都会用到，若是使用Api Leaf自动生成文档，极可能须要重复填写屡次User各个字段的说明，这是咱们不能接受的。

Api Leaf的思路是，将经常使用的数据结构建立成数据字典并保存到项目中去，一方面能够方便前端人员快速获取经常使用的数据结构定义，另外一方面能够在数据结构重复出现时，自动匹配相关的字典，这样就减小了重复编写说明的过程。

说了这么多，咱们仍是举个例子来看看数据字典是如何使用的吧：

建立一个数据字典

进入指定项目的文档查看页面，点击顶部导航栏的数据字典便可进入数据字典的列表页面，而后点击添加新字典按钮进入数据字典的编辑页面：

在编辑页面填写好数据字典的类型名和描述（注意一个项目中不能有两个类型名相同的数据字典）后，能够经过手动添加的方式补充数据字典的各个字段定义和说明，也能够从一个示范的JSON中解析出一个数据字典。

举个例子，咱们使用刚才响应中返回的User对象JSON来建立这个数据字典：

点击解析后，就可以自动补充全部的字段名和类型了，你须要手动检查这些类型是否正确，并补充好相应的说明：

最后点击Done按钮就能够生成一个完整的数据字典了。

自动匹配

如今咱们有了一个数据字典，让咱们来看看如何使用自动匹配功能吧。

假设如今项目中多了另外一个接口/user/{id}/profile，经过这个接口能够获取指定用户的我的信息（也就是他的User模型），而后咱们进行一次测试，获得下面的响应:

{
	"code": 0,
	"user": {
		"id": 17,
		"name": "lumin",
		"sex": "male",
		"age": 20
	}
}
复制代码

如今咱们须要生成文档了，这时候你发现这个user类型咱们在以前的登陆接口里已经定义过一次了，难不成又要从新写一遍每一个字段的描述？

答案固然是NO，只要你已经将这个数据结构定义进了数据字典，那么在这一步你就没必要填写任何的body_description字段，直接点击生成文档，而后进入项目文档的查看页面，你会发如今响应的说明字段，多了几个按钮...

接下来点击这个按钮，神奇的事情发生了：Api Leaf将根据所选字段的全部key，自动去项目的数据字典中匹配最可能的数据定义，在这个例子中，咱们将能够获得匹配率达到100%的User数据定义，没错，咱们要的就是它了！

匹配功能将会尽量地搜寻数据字典中最相似的结构，可是也会出现搜索不到或者匹配率很低的状况，好比下面这样：

匹配到的字段将会加粗显示。

当匹配率低于60%的时候，颇有可能这并非你须要的数据定义，这时候仍是老老实实地补充数据字典或者字段定义吧~

只要定义好经常使用的数据字典，生成文档时就会省去不少力气，所以建立好项目的基本数据定义（好比数据库表结构）后，就把他们补充到数据字典中去吧！

注意

数据字典目前暂不支持嵌套的层级字段定义，匹配结果也仅供参考，建议先后端在使用此功能前先提早作好沟通。

一个完整的文档结构

使用Api Leaf建立一个项目文档的基本流程已经介绍完了，下面咱们站在前端/客户端开发者的角度，看看一个完整的项目文档可以提供哪些信息。

你能够点击此处查看官方提供的一个简单示范文档。

Api Leaf中一个完整的项目文档包括如下3部分：

1. API接口文档：由HTTP测试生成并聚合
2. 状态码列表：项目中使用到的各类状态码
3. 数据字典：经常使用的数据结构定义

经过顶部的导航栏能够快速在三部分间切换，另外每一个部分都提供了左侧的导航栏，用于快速定位相关定义的位置：

其中API接口文档部分还提供了分组和排序、筛选等功能，为了方便阅读人员找到文档，咱们还提供了收藏功能，能够保存最近常用的文档。

其余

Api Leaf还提供了诸如团队协做等其余功能，在此不一一赘述，请查看说明文档了解更多细节。

这是我作的第一个开源工具，更多的是站在本身团队的使用角度上进行的设计和开发，但我相信大多数和咱们团队同样的中小型敏捷开发团队，尤为是学生团队，须要这样一款工具来方便成员之间的沟通和交流。

由于是我的独立开发，因此在页面美观、使用逻辑方面尚有须要打磨的地方，后面我也会持续更新和优化相关功能。

欢迎广大开发者试用并提出宝贵意见！

• 做者：刘明@不洗碗工做室
• github：https://github.com/MarkLux/ApiLeaf

顺便一提，我在页面上埋了几个彩蛋，有兴趣的同窗能够找找看~