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

4,172 阅读11分钟

简介

我相信很多编写后台接口的同学们都跟我一样,对于接口文档的编写头痛不已:编写文档费时、费力,实在是打击开发者的开发热情,尤其是在中小型项目的敏捷开发,往往编写文档花的时间比接口开发的时间还长。

对于大型项目和成熟团队,一般都会有成熟的接口自动化测试工具,集接口测试、自动构建和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

顺便一提,我在页面上埋了几个彩蛋,有兴趣的同学可以找找看~