文档驱动API设计

在日常开发工作中,API的开发及对接工作几乎是在所难免的。无论作为一个API的设计者还是调用者,相信都对API文档有各种各样的奇葩经历。一份好的API文档对开发人员来说实在是太重要了,他带来的效率提升是显而易见的。那么如何去编写一份好的API文档呢,今天来说说文档驱动的API设计。

「代码未动,文档先行」这可以说是文档驱动API设计的核心了,在开始编写API代码之前,先将API设计好,然后输出成API文档。在设计的过程中,实际上是对API细节的梳理,一个功能或者一组功能,需要用到哪些API,这些API都需要哪些请求参数和返回参数。当你将这些API输出成文档后,基本上大致的结构已经确定下来,不像之前只是脑子里有个粗糙的构思。接下来的事情就是和API相关的开发者和调用者进行文档的评审,和大家一起确认这些API是否都合理,看有没有遗漏的,同时也是让相关人员都清楚各系统模块间的调用逻辑。当文档评审通过后,代表大家对API的设计达成了统一,这时候每个人就可以按照文档开始各自的工作了。无论是客户端也好还是服务端也好,相互不影响,各自把各自的代码写好,等到都完成后只需要进行对接联调就可以了,不需要等待,不需要中断。

我之前看到有人吐槽说他们的服务端开发人员每次都是把API写完后才去写API文档,然后再把API文档发给客户端开发人员去开发。我觉得这种低效的做法需要赶紧停止,可能你的一个版本开发完,你的竞争对手已经迭代了2、3个版本了。在没有提前设计就进入开发环节这是一种冒险行为,可能你写了一堆代码后发现有些API可以合并,而有些API又需要拆分,或者有些API少了请求、返回参数,又要回去补。修修改改一来回,眼瞅着deadline就到了,结果API文档还没写,客户端那边开发还等着呢,这绝对是一场噩梦。于是你匆匆忙忙写了一份简陋的API文档交给客户端开发,结果客户端又调不通API总是找你,这是怎样的感觉?

所以在开始开发API之前先将API文档输出出来,这可以帮助你梳理一遍API实现的逻辑,一些能避免的坑就提前避开了,到了编码环节便如行云流水,同时和你配合的客户端开发同学也可以愉快地撸代码了。

我们自己的团队平时也是如此,每次版本功能定下来后,由后端的同学开始设计API,设计完成后叫上前端的同学一起对API文档进行评审,在评审阶段对一些设计不合理或需要调整的地方就及时处理了,评审通过后大家就都可以同时开始开发工作,等到都开发完成后一起对接联调,再之后就顺利提测了,非常高效。

整个过程我们都将API文档放在ApiCat上进行管理,如果遇到开发过程中发现有个别API需要做一些调整,可以直接在ApiCat上对文档进行修改,修改会后at前端的同学,提醒关注API的变化,这样前端同学就会收到通知得知API做了调整,便可以及时对代码进行调整了。

一份好的API文档是团队的宝贵资源,从长远来看,拥有优秀的文档可以节省团队大量时间,并且可以帮助你轻松地构建手头的项目。

ApiCat – 高效API文档管理工具

发表评论

电子邮件地址不会被公开。 必填项已用*标注