接口管理产品白皮书

第一章 产品概述

接口管理系统是面向开发、测试、产品等项目研发人员开发的一套接口管理工具，围绕接口文档定义，集合了文档管理、接口 Mock、接口调试、团队协同等功能。主要目的是规范接口文档格式、提高文档编写及使用效率，助力团队人效提升。

产品目标: 功能齐全，简单、好用的接口管理系统。

第二章 产品优势

2.1 专业的接口编辑器

从接口编辑和录入行为入手，规范接口文档的格式、内容，确保接口定义完善、正确。并且提供简便、灵活的编辑方式，提高文档编写效率。

2.2 可代码解析的文档

通过接口编辑器录入规范化的接口文档之后，可在平台上导出接口文档的 JSON 格式数据，可使用代码对接口文档数据进行处理。接口文档数据可作为接口自动化测试、接口调试的模板数据。

2.3 一站式接口服务

通过接口编辑器录入规范化的接口文档之后，可以在接口管理系统中生成和获取该接口的 Mock 数据，也可以通过接口调试工具便捷的对部署的接口服务进行调试。

2.4 灵活的团队权限及发布管理

按照项目维度发布接口文档，可以给用户设置管理员、可读写、仅可读的不同权限；另外，项目设置为开放状态后，平台用户可通过检索操作查找对应项目文档查阅，便于团队协作。

第三章 应用场景

• 解决前后端接口沟通问题

  统一接口规范和交付方式，和邮件、Word 形式交付接口文档说再见，信息不再遗漏；
  统一的接口文档管理和查阅平台，沟通不再占去大量工作时间。

• 让前后端开发同步进行

  在某个接口后端还未完成的情况下，前端调用 Mock 数据接口进行调试，不影响开发进度；
  后端接口开发完毕，通过接口调试工具进行请求参数和返回值校验。

• 接口定义更完整

  字段 Wiki，主动备注字段笔记，字段定义逻辑及变动情况清晰可见；
  人员流动，接口定义不再无法查证。

• 接口与日俱增，专业管理工具成为刚需

  随着项目业务走向复杂，接口数量越来越多，方便、专业的接口管理工具成为刚需；
  需求文档快速变动，格式化输入让接口更新不再难，且一人改动，项目组可见。

第四章 总体设计

4.1 产品架构

4.2 部署架构

第五章 产品功能

5.1 接口编辑器

提供便捷的接口文档编辑器，方便用户快捷和规范地定义接口的名称、请求方式、URL路径、描述、入参和返回值信息。在编辑器中编辑字段时，可以添加字段的默认值及契约，保存的数据用于 Mock 数据和接口调试。

5.2 字段 Wiki

查阅接口文档时，可以给字段添加 Wiki 文档，补充说明更详细的字段信息，尤其是当业务逻辑比较复杂时，添加字段 Wiki 能够方便自己或他人有需要时更全面的了解字段含义。

5.3 Mock 数据

在项目开发过程中，前端同学可在接口 Mock 数据页面查看 Mock 数据，同时支持通过统一的 Mock 数据地址直接在工程中访问该数据；也可根据需要修改 Mock 数据内容。

5.4 接口调试

在接口调试页面可以发起对接口的访问，接口文档作为数据定义的模板，提高了请求编辑效率。

5.5 团队成员管理

团队成员管理页面可以对成员权限进行细分，可设置为管理员，赋予读写权限或只读权限。

5.6 接口操作记录及变更文档

接口的每一次保存可生成操作动态记录到系统中，在接口动态中可查看详细改动内容。如果某个操作记录关联到某个产品需求、或者需要同步给其他项目成员，可以在接口保存时生成变更文档。变更文档会作为重要的接口变动长久保存在系统中，供后续所有项目成员查看。

第六章 部署环境要求

6.1 硬件要求

服务器资源

6.2 软件要求

操作系统 中间件