对 API 管理的一些思考

前言

目前市场上有不少 API 管理平台，这种平台一多，开发团队在作选型时 就须要花更多的时间去分析和对比，如何选择一个适合本身团队的 API 管理工具很是重要，由于这很大程度决定了团队之间的协做方式。

为何须要 API 管理

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

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

咱们真正须要的是什么

不妨从结果导向来看，若是站在 API 接口的消费端角度，那咱们须要的 API 文档必须具备如下几个重要特征：

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

这个时候咱们就会发现，这些东西，基本上都是人来作，平台和工具只不过提供更加好看的界面，更加方便的工具来帮咱们更快的作到第 三、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 是最符合的。