前言

本文原创，著作权归WGrape所有，未经授权，严禁转载

一、背景

在项目的开发流程中，接口文档的管理一直是一个难以高效实践的重要难题，具体表现在以下方面。

• 接口文档是一个很重要但却没有太多人重视的东西
• 没有人喜欢写接口文档，特别是在时间紧迫情况下，接口文档给出的时间晚或有瑕疵都是常事
• 随着前后端工作推进，难免出现接口文档中字段或结构的调整，导致实际接口表现和接口文档不一致

这些问题，虽然看起来只会影响前端的效率，但实际上无论是对项目开发流程中的哪一方，都有直接或间接的影响。

比如当前端发现接口文档有问题时，就会去找后端询问，多次发生这样的情况一定会增加沟通成本，影响双方效率。

所以如果有良好的接口文档的治理方案，对整个项目开发和维护都会有非常大的质量和效率提升。

二、问题痛点

根据调查发现，在项目迭代下，关于接口文档主要会出现如下问题

1. 前端已经开始开发，但是接口文档还没有（30%）
2. 前端已经开始开发，但是后端接口还处于无法调通的情况（60%）
3. 前端已经开始开发，但是接口文档经常处于和实际返回值不一样的情况（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、最好的不一定是最合适的

虽然很多框架功能十分强大，但这些优势同时也会成为劣势。复杂的部署、较大的学习成本、冗余的功能等等这些都会导致这类框架非常笨重。所以选择一个合适自己的才是最重要的。