共计 861 个字符,预计需要花费 3 分钟才能阅读完成。
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