对 API 管理的一些思考

3,121 阅读4分钟

前言

目前市场上有很多 API 管理平台,这种平台一多,开发团队在做选型时 就需要花更多的时间去分析和对比,如何选择一个适合自己团队的 API 管理工具非常重要,因为这很大程度决定了团队之间的协作方式。

为什么需要 API 管理

传统的 API 管理是采用 word 文档的方式,这种方式的缺陷在于它难以维护和管理,同时容易造成不同步,随着时间的推移,API 文档散落在各个地方,导致接口数据格式不一致,接口频频报错,这会造成团队之间的不信任以致于 API 文档逐渐被废弃;这种情况一发生,就会看到开发人员之间频繁的通过询问、沟通、联调和查看代码来确定 API 接口的各种细节,团队之间更容易互相推卸责任,开发成本逐渐增加。

有趣的是,这种问题不是给开发团队 丢一个功能超强的 API 管理平台就可以搞定的。这需要使用合适的管理策略。

我们真正需要的是什么

不妨从结果导向来看,如果站在 API 接口的消费端角度,那我们需要的 API 文档必须具有以下几个重要特征:

  1. 描述恰当
  2. 划分合理
  3. 及时同步
  4. 通过测试
  5. 方便使用

这个时候我们就会发现,这些东西,基本上都是人来做,平台和工具只不过提供更加好看的界面,更加方便的工具来帮我们更快的做到第 3、4 点。这个时候我们才恍然大悟,API 管理重点在人,不在工具。

如何管理

谁产生,谁负责管理。 为了让这种理念变得更容易被接受,需要把它行成一种习惯,因此最好跟对方最擅长的技能结合在一起,加上适当约束,并且赋予这个人一定的权利。

  • 工具最好跟代码结合(慢慢形成习惯)。
  • 通过测试(约束)。
  • 拥有部分接口的定义权(赋予一定的权利)。

平台分析

在线产品

这种产品非常多,基本上可以归为 免费 和 收费 两种,部分产品提供更多额外的服务,例如监控、自动化测试等。

优势

  1. 不需要维护服务器
  2. 提供团队协作功能
  3. 提供在线接口测试
  4. 接口变更通知(不一定有)
  5. 多项目管理

劣势

  1. 平台随时可能 停止维护
  2. 接口需要手工同步
  3. 各大平台的 接口格式 不太统一,迁移是问题
  4. 接口契约无法保证(是否通过测试?格式是否正确?)

框架集成

框架集成是指 把 API 文档自动生成框架集成到 开发环境中,目前 基于 spring 的主要有 springfox-swagger2 和 spring rest doc。

Springfox-Swagger2

劣势

  1. 侵入式
  2. 增加少量的学习成本

优势

  1. 安全,可定义接口访问鉴权
  2. 代码即文档
  3. UI 美观
  4. 提供测试
  5. 社区提供 spring-boot 集成
Spring REST Doc

产品的定位是测试驱动 API 文档,提供手写文档和自动生成相结合,基于 API 测试来自动生成文档,只有测试通过才生成 API 文档,因此可以保证文档的准确性。

劣势

  1. 增加少量的学习成本
  2. 文档需要 一点手工配置,好在配置相对简单
  3. 发布接口前需要付出一些时间来执行 api 测试

优势

  1. 安全,可选择文档共享范围
  2. 无侵入性
  3. 接口契约(API 测试通过后,才能生成离线 html API 文档)
  4. 代码即文档
  5. spring 生态,集成方便

自建

当框架集成 和 公网在线平台 都不能满足需要求时,即可自建 API 管理平台。目前这方面的开源工具也很多,常用的在思维导图中列出。

优势

  1. 可控
  2. 可定制

劣势

  1. 需要维护服务器
  2. 接口需要手工同步
  3. 接口契约无法保证(是否通过测试?格式是否正确?)

总结

文章表达了我自己对 API 管理的看法,也简单分析了市场上的一些 API 工具,粗粒度地总结了不同产品的选择的优劣势。API 管理的目标,是为了便于团队协作。在基于上面那些理解之后,我竟然发现 Spring REST Doc 是最符合的。