文章内容更新请以 WGrape GitHub博客 : 关于接口文档高效治理方案的研究和思考 为准
前言
本文原创，著作权归WGrape所有，未经授权，严禁转载
一、背景
在项目的开发流程中，接口文档的管理一直是一个难以高效实践的重要难题，具体表现在以下方面。
- 接口文档是一个很重要但却没有太多人重视的东西
- 没有人喜欢写接口文档，特别是在时间紧迫情况下，接口文档给出的时间晚或有瑕疵都是常事
- 随着前后端工作推进，难免出现接口文档中字段或结构的调整，导致实际接口表现和接口文档不一致
这些问题，虽然看起来只会影响前端的效率，但实际上无论是对项目开发流程中的哪一方，都有直接或间接的影响。
比如当前端发现接口文档有问题时，就会去找后端询问，多次发生这样的情况一定会增加沟通成本，影响双方效率。
所以如果有良好的接口文档的治理方案，对整个项目开发和维护都会有非常大的质量和效率提升。
二、问题痛点
根据调查发现，在项目迭代下，关于接口文档主要会出现如下问题
- 前端已经开始开发，但是接口文档还没有（30%）
- 前端已经开始开发，但是后端接口还处于无法调通的情况（60%）
- 前端已经开始开发，但是接口文档经常处于和实际返回值不一样的情况（10%）
上述问题的背后都指向了同一个问题 ：如何高效治理接口文档问题
三、常见方案
1、基于Wiki的接口文档管理
大部分公司的接口文档都会使用Wiki作为主要的管理方式，如Confluence Wiki、飞书等。
(1) 优势
- 安全稳定
- 案例经验丰富
(2) 劣势
- 管理方式落后
- 过于依赖人工管理，不便于自动化操作
(3) 总结
这种方案适用于迭代速度慢、安全性要求高、传统型的大规模公司或团队使用
2、基于Postman的接口文档管理
Postman是最流行最强大的API管理工具，支持接口调用和测试、自动生成接口文档、团队协作和分享。
(1) 优势
- 适合小团队使用
- 功能强大完善
(2) 劣势
- 公司实践案例少
- 网络服务不稳定
- 不支持本地部署
- 高级功能需要付费
(3) 总结
这种方案适用于外包、在校学生、安全性要求低、临时短暂性的小团队使用
3、基于Swagger的接口文档管理
Swagger是新一代的接口文档管理工具，其思想是代码即文档，在写代码的时候通过注释/注解，实现接口文档的自动生成。
(1) 优势
- 开源免费
- 项目成熟稳定
- 功能强大完善
- 支持私有部署
(2) 劣势
- 过于繁重
- 上手比较慢
- 维护成本过高
(3) 总结
这种方案适用于有专人维护、稳定型的大规模公司或团队使用
4、其他接口管理平台
对于其他的接口管理平台，基本上和【基于Swagger的接口文档管理】类似，无非是更简单还是更复杂的问题，在这里就不再赘述。
四、如何高效管理
1、保持集中统一
对于项目流程来说，如果所有和开发相关的工作都集成在代码中，会保持管理上的集中统一，减少切换开销，提高工作效率。
2、完全自动化
接口文档的管理应该自动集成在日常开发中，并做到与开发工作中的结合与完全自动化。
3、最好的不一定是最合适的
虽然很多框架功能十分强大，但这些优势同时也会成为劣势。复杂的部署、较大的学习成本、冗余的功能等等这些都会导致这类框架非常笨重。所以选择一个合适自己的才是最重要的。
