在日常开发工作中，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文档是团队的宝贵资源，从长远来看，拥有优秀的文档可以节省团队大量时间，并且可以帮助你轻松地构建手头的项目。
网友评论