前言
目前市场上有很多 API 管理平台,这种平台一多,开发团队在做选型时 就需要花更多的时间去分析和对比,如何选择一个适合自己团队的 API 管理工具非常重要,因为这很大程度决定了团队之间的协作方式。
为什么需要 API 管理
传统的 API 管理是采用 word 文档的方式,这种方式的缺陷在于它难以维护和管理,同时容易造成不同步,随着时间的推移,API 文档散落在各个地方,导致接口数据格式不一致,接口频频报错,这会造成团队之间的不信任,以致于 API 文档逐渐被废弃;这种情况一发生,就会看到开发人员之间频繁的通过询问、沟通、联调和查看代码来确定 API 接口的各种细节,团队之间更容易互相推卸责任,开发成本逐渐增加。
有趣的是,这种问题不是给开发团队 丢一个功能超强的 API 管理平台就可以搞定的。这需要使用合适的管理策略。
我们真正需要的是什么
不妨从结果导向来看,如果站在 API 接口的消费端角度,那我们需要的 API 文档必须具有以下几个重要特征:
- 描述恰当
- 划分合理
- 及时同步
- 通过测试
- 方便使用
这个时候我们就会发现,这些东西,基本上都是人来做,平台和工具只不过提供更加好看的界面,更加方便的工具来帮我们更快的做到第 3、4 点。这个时候我们才恍然大悟,API 管理重点在人,不在工具。
如何管理
谁产生,谁负责管理。 为了让这种理念变得更容易被接受,需要把它行成一种习惯,因此最好跟对方最擅长的技能结合在一起,加上适当约束,并且赋予这个人一定的权利。
- 工具最好跟代码结合(慢慢形成习惯)。
- 通过测试(约束)。
- 拥有部分接口的定义权(赋予一定的权利)。
平台分析
在线产品
这种产品非常多,基本上可以归为 免费 和 收费 两种,部分产品提供更多额外的服务,例如监控、自动化测试等。
优势
- 不需要维护服务器
- 提供团队协作功能
- 提供在线接口测试
- 接口变更通知(不一定有)
- 多项目管理
劣势
- 平台随时可能 停止维护
- 接口需要手工同步
- 各大平台的 接口格式 不太统一,迁移是问题
- 接口契约无法保证(是否通过测试?格式是否正确?)
框架集成
框架集成是指 把 API 文档自动生成框架集成到 开发环境中,目前 基于 spring 的主要有 springfox-swagger2 和 spring rest doc。
Springfox-Swagger2
劣势
- 侵入式
- 增加少量的学习成本
优势
- 安全,可定义接口访问鉴权
- 代码即文档
- UI 美观
- 提供测试
- 社区提供 spring-boot 集成
Spring REST Doc
产品的定位是测试驱动 API 文档,提供手写文档和自动生成相结合,基于 API 测试来自动生成文档,只有测试通过才生成 API 文档,因此可以保证文档的准确性。
劣势
- 增加少量的学习成本
- 文档需要 一点手工配置,好在配置相对简单
- 发布接口前需要付出一些时间来执行 api 测试
优势
- 安全,可选择文档共享范围
- 无侵入性
- 接口契约(API 测试通过后,才能生成离线 html API 文档)
- 代码即文档
- spring 生态,集成方便
自建
当框架集成 和 公网在线平台 都不能满足需要求时,即可自建 API 管理平台。目前这方面的开源工具也很多,常用的在思维导图中列出。
优势
- 可控
- 可定制
劣势
- 需要维护服务器
- 接口需要手工同步
- 接口契约无法保证(是否通过测试?格式是否正确?)
总结
文章表达了我自己对 API 管理的看法,也简单分析了市场上的一些 API 工具,粗粒度地总结了不同产品的选择的优劣势。API 管理的目标,是为了便于团队协作。在基于上面那些理解之后,我竟然发现 Spring REST Doc 是最符合的。