API文档自动集成系统设计流程

背景

WooshPay官网需要一个官方的API文档系统，用于向客户以及第三方提供接口信息展示。考虑到日后此文档系统的复杂性的增加以及减少维护的成本，这里需要开发一套API文档的自动化集成系统，用于方便API文档的自动生成与维护管理，根本性解决目前整个API文档靠人工原始维护的现状。

目标

整个系统我们最终的目前是希望去提供一整套对内、对外，集接口定义、Mock联调、测试用例到自动化部署的一整套完整流程。 对此我们将整个系统的实现目标进行分级，将目标进行一个详细的罗列：

P1：

目标：支持基本团队协作

• 接口定义

• 接口联调

• 接口文档自动生成(内部使用)

• 接口数据保存

P2：

目标：支持对外API文档自动生成

• 接口Mock

• 支持开发、测试、生产等不同环境

• 接口文档自动生成(对外开放展示)

P3：

目标：构建完整API开发、调试、验收产研流程

• 测试用例集成

• 接口单测与压测

• 集成Jekins等自动化工具

设计流程

设计流程图简要概览：

流程说明：

1. API定义： 接口在进行具体开发之前需要提前将API接口文档定义好，如需中途修改则同样需要及时同步修改接口文档，接口定义将被保存为JSON数据，方便维护调用。

2. 将第一步定义好的接口生成JSON数据，这里由APIFox这样的工具来执行，对于接口的数据结构包括有：

   • 方法类型

   • 请求参数

   • 接口描述

   • 响应示例

   • 字段备注等... 原则上接口API可以包含的字段均在这一阶段决定，如若后续需要额外再此基础上扩展。

3. API文档生成，这里主要分为两种，一种内部自用文档，由APIFox自动生成，第二种对外文档由前端根据接口数据来动态渲染生成，这里便是主要的实际工作开发量。 需要注意的是，为了确保对外API文档的稳定性，这里需要单独建立一个接口项目，将其与其他接口文档独立开来，严格把控生产环境文档的修改权限，确保对外公开文档的正确性。

4. 集成相关需求，P1~P2，我们主要确保API文档的使用便利与可维护性，而集成相关的需求属于P3阶段的任务。P3阶段，我们将主要与测试用例进行结合，方便后续项目的验收流程。

实现步骤

1. 将接口文档定义迁移到APIFox，后端同学的全部工作便是这个

2. 选择任意项目进行实践，将整个API定义到接口联调的流程熟悉走通

3. 单独创建对外API项目，UI同学提供API文档设计稿，前端开始根据设计稿与接口数据开始动态生成项目

4. 后续维护：对于任意接口的新增与编辑仅仅需要修改APIFox上面的接口实例，便能即时生效，无需任何代码修改、发布流程，但也因此要严格把控修改权限，防止误操作导致文档数据丢失或错乱。

持续化集成推进

• 测试用例集成

• 脚本集成

• 接口Mock

• 自动化测试

• 性能测试

• CI/CD集成