API文档之团队协作
API是程序的关键,与之对应的API文档也是项目中重要的组成部分。API从设计开始到停用这个过程称之为API生命周期,而文档的作用贯穿API整个生命周期中的各个阶段,让用户可以清楚的知道API每个阶段的情况。
一份好的API文档不仅包括API的基本信息,如url、请求头部,请求参数等,还包括API的示例等信息。API文档涉及的点很细,并且不只是开发人员查看API文档,非技术人员或企业外部用户也会涉及,这使得API文档的编写难上加难。
API文档由设计API或进行API开发的人员编写是最适合的,他们知道API的详细信息,所以在编写上不仅简单且不容易出错,但这只对于小团队有利。当项目达到一定规模或API达到一定数量时,如果还是由开发人员去编写与维护,则可能造成API文档混乱、难以维护的结果。
既然API文档贯穿API的整个生命周期,那么是否可以在API的各个阶段分不同角色对API进行维护呢?答案是可以的。
API在设计初时即可将API记录为文档。
设计API的人员确认API的功能与基本信息后,可记录在API文档中,并生成迭代计划,这就是一个API的开始。
经过确认后生成MockAPI,前后端人员分工合作,前端开始使用MockAPI进行开发,后端则参考API文档开发API。
开发人员开发完API后替换,添加测试环境Host,由测试人员开始测试,并生成测试用例,在此过程中完善API文档。
当确认API在测试环境可以正常使用后,则选择合适的时间把API更新到正式环境,此时需要通知到响应的人员。
需要对API进行维护时则重复以上过程,直至API弃用,至此API的生命周期结束。在整个过程中,我们把API的不同阶段划分出来,且每个阶段由不同的人员进行编写,这种做法有利于分担开发人员的工作,且各个阶段的人员编写的文档也是标准、专业的。
本文使用了API管理平台Eolinker进行演示,结合自身对API生命周期的看法,编写了此文章,欢迎各位对API生命周期管理感兴趣的小伙伴与我交流。
使用地址:www.eolinker.com