《 API 管理平台 XXL-API 》

一、简介

1.1 概述

XXL-API 是一个简洁易用 API 管理平台，提供 API 的"管理"、"文档"、"Mock"和"测试"等功能。现已开放源代码，开箱即用。

1.2 特性

• 1 、极致简单：交互简洁，一分钟上手；
• 2 、项目隔离： API 以项目为维度进行拆分隔离；
• 3 、分组管理：单个项目内的 API 支持自定义分组进行管理；
• 4 、标记星级：支持标注 API 星级，标记后优先展示；
• 5 、 API 管理：创建、更新和删除 API ；
• 6 、 API 属性完善：支持设置丰富的 API 属性如： API 状态、请求方法、请求 URL 、请求头部、请求参数、响应结果、响应结果格式、响应结果参数、 API 备注等等；
• 7 、 markdown ：支持为 API 添加 markdown 格式的备注信息；
• 8 、 Mock ：支持为 API 定义 Mock 数据并制定数据响应格式，从而快速提供 Mock 接口，加快开发进度；
• 9 、在线测试：支持在线对 API 进行测试并保存测试数据，提供接口测试效率；

1.3 下载

源码地址 (将会在两个 git 仓库同步发布最新代码)

• github 地址
• git.osc 地址

博客地址 (将会在两个博客同步更新文档)

• oschina 地址
• cnblogs 地址

技术交流群 (仅作技术交流)

• 群 2 ： 438249535
• 群 1 ： 367260654 （群 1 已满，请加群 2 ）

1.4 环境

• Servlet/JSP Spec ： 3.0/2.2
• JDK ： 1.7+
• Tomcat ： 7+/Jetty8+
• Mysql ： 5.6+
• Maven ： 3+

二、快速部署

2.1 初始化“调度数据库”

请下载项目源码并解压，获取 "初始化 SQL 脚本"，脚本位置：

/xxl-api/db/xxl-api-mysql.sql 

2.2 编译源码

解压源码,按照 maven 格式将源码导入 IDE, 使用 maven 进行编译即可，源码结构如下图所示：

2.3 配置 JDBC 连接

在以下项目文件中设置应用的 JDBC 连接；

/xxl-api/xxl-api-admin/src/main/resources/xxl-api.properties 

2.4 部署

将应用"xxl-api-admin"部署在容器如 Tomcat 下之后，启动后访问即可进入以下界面：

三、项目管理

系统中 API 以项目为单位进行管理，因此首先需要管理项目；项目管理界面如下图所示；

3.1 新建项目

进入项目管理界面，点击右侧"+新增项目"按钮可新建项目，如下图所示：

项目属性说明：

项目名称：项目的名称； 项目描述：项目的描述信息； 访问权限："公开"权限，表示所有人可操作；"私有"权限，表示只有管理员或者项目成员可以操作（功能自测中，即将推送）； 跟地址-线上环境：项目线上环境跟地址，项目中的 API 共用该跟地址； 跟地址-预发布环境：项目预发布环境跟地址； 跟地址-测试环境：项目测试环境跟地址； 版本：项目的版本信息； 

3.2 更新项目

进入项目管理界面，点击项目右侧的"编辑"按钮可更新项目信息，如下图所示；

3.3 删除项目

进入项目管理界面，点击项目右侧的"删除"按钮可删除项目信息；注意，项目中存在 API 时不允许删除；

四、 API 管理

在项目管理界面，点击项目右侧的"进入项目"按钮，可进入接口管理界面，如下图所示：

4.1 API 分组管理

• 新增 API 分组

如下图，点击"左侧接口分组区域"右上角的"+"按钮，可新增 AIP 接口分组；（点击"全部"将会展示项目中所有分组下的接口；"默认分组"为系统分组，不允许删除；）

接口分组属性说明：

分组名称：分组的名称 分组排序：分组的排序顺序，数字类型，值越小越靠前； 

• 更新 API 分组

在"左侧接口分组区域"，点击对应的 API 分组，右侧将会展示该分组下 API 接口列表；如下图，点击接口列表顶部的"编辑分组"按钮（新增的 API 分组才会有该功能），可修改 API 分组信息；

• 删除 API 分组

在"左侧接口分组区域"，点击对应的 API 分组，右侧将会展示该分组下 API 接口列表；点击接口列表顶部的"删除分组"按钮（新增的 API 分组才会有该功能），可修改 API 分组信息；

4.2 API 管理

• 新增 API

如下图，在 API 接口管理界面，点击接口列表顶部的"新增接口"按钮，可进入新增接口界面； 在新增接口界面，如下图所示，可以设置接口的 API 状态、请求方法、请求 URL 、请求头部、请求参数、响应结果、响应结果格式、响应结果参数、 API 备注等等信息；

API 属性说明：

基础信息： 接口分组：接口所属的分组； 接口状态：接口的状态，在接口列表中，启用状态接口用绿色圆圈标识，维护状态接口用黄色圆圈标识，废弃状态接口用灰色圆圈标识； 请求方法：请求方法，如 POST 、 GET 等； 接口 URL ：接口请求的 URL 地址，注意此处为相对地址，跟地址从所属项目的跟地址属性上获取； 接口名称：接口的名称； 请求头部：同一接口支持设置多个请求头部； 头部标签：请求头部的类型，如 Accept-Encoding ； 头部内容：请求头部的数据，如 Accept-Encoding 头部标签的头部内容 UTF-8 ； 请求参数：同一接口支持设置多个请求参数； 是否必填：该参数是否必填； 参数类型：该参数的数据类型，如 STRING ； 参数名称：参数的名称； 参数说明：参数的说明； 响应结果：分别支持设置 "成功响应结果" 和 "失败响应结果"，作为接口响应数据的参考； 响应数据类型(MIME)：响应结果类型，如 JSON 、 XML 等； 响应结果数据：响应结果的数据，如响应结果类型为 JSON 时可设置响应结果数据为一段 JSON 数据； 响应结果参数：对接口"响应结果"中参数的补充说明，如响应结果类型为 JSON 时，可在此处一一列出 JSON 各个字段的参数信息； 是否非空：该参数是否可能为空； 参数类型：该参数的数据类型，如 STRING ； 参数名称：参数的名称； 参数说明：参数的说明； 接口备注： markdown 方式的接口备注； 

• 更新 API

在 API 接口管理界面，点击接口右侧的"更新接口图标"按钮，可进入更新接口界面；

• 删除 API

在 API 接口管理界面，点击接口右侧的"删除接口图标"按钮，可删除接口数据；

4.3 API-Mock

• 新增 Mock 数据 在 API 接口管理界面，点击接口名称，进入"接口详情页"，在接口详情页的"Mock 数据"模块右上角点击"+Mock 数据"按钮，可新增 Mock 数据；

Mock 数据属性说明：

数据类型(MIME)：响应结果类型，如 JSON 、 XML 等； 结果数据：响应结果的数据，如响应结果类型为 JSON 时可设置响应结果数据为一段 JSON 数据； 

• 更新 Mock 数据 在"接口详情页"的"Mock 数据"模块，点击 Mock 数据列表右侧的"修改"按钮，可修改 Mock 数据；

• 删除 Mock 数据

在"接口详情页"的"Mock 数据"模块，点击 Mock 数据列表右侧的"删除"按钮，可删除 Mock 数据；

• 运行 Mock 数据

在"接口详情页"的"Mock 数据"模块，点击 Mock 数据列表右侧的"运行"按钮，可运行 Mock 数据； 系统将会为每一条 Mock 数据生成一个唯一的 Mock 连接，访问该连接将会按照设置的数据类型如 JSON 返回对应格式的 Mock 数据，如下图所示；

4.4 API-测试

• API-测试 进入"接口详情页"，点击"Test 历史"模块右上角的"+接口测试"按钮，可进入"接口测试界面"， 该界面将会自动初始化接口 URL （测试界面支持选择运行环境，将会自动生成不同环境的完整 URL 连接）和参数等信息。 只需要填写测试的参数值，点击下方"运行"按钮，即可发起一次接口请求，请求结果将会在下方显示出来：

• 保存 Test 历史

在"接口测试界面"，在进行接口测试后, 点击下方"保存"按钮将会把本次测试数据（接口 URL ，测试参数等信息）保存下来。 在"接口详情页"的"Test 历史"模块可查看所有的接口测试历史记录。点击一次测试记录右侧的"运行"按钮，将会进入到本次测试记录对应的接口测试界面，还原当时测试时使用的测试数据；

• 删除 Test 历史

在"接口详情页"的"Test 历史"模块，点击测试历史记录右侧的"删除"按钮可删除本条记录；

五、用户管理

5.1 、新增用户

进入用户管理界面，点击右上角"+新增用户"按钮，可添加用户信息；

用户属性说明：

登录账号：用户的登录账号； 登录密码：用户的登录密码； 用户类型： 普通用户：只允许操作公开项目，或者自己拥有项目权限的私有项目； 超级管理员：拥有所有项目的操作权限； 真实姓名：用户的真实姓名； 

5.2 、更新用户

进入用户管理界面，点击用户列表页中用户右侧的"编辑"按钮可编译用户信息；

5.3 、删除用户

进入用户管理界面，点击用户列表页中用户右侧的"删除"按钮可删除用户信息；

六、版本更新日志

6.1 版本 V1.0.0 ，新特性

• 1 、极致简单：交互简洁，一分钟上手；
• 2 、项目隔离： API 以项目为维度进行拆分隔离；
• 3 、分组管理：单个项目内的 API 支持自定义分组进行管理；
• 4 、标记星级：支持标注 API 星级，标记后优先展示；
• 5 、 API 管理：创建、更新和删除 API ；
• 6 、 API 属性完善：支持设置丰富的 API 属性如： API 状态、请求方法、请求 URL 、请求头部、请求参数、响应结果、响应结果格式、响应结果参数、 API 备注等等；
• 7 、 markdown ：支持为 API 添加 markdown 格式的备注信息；
• 8 、 Mock ：支持为 API 定义 Mock 数据并制定数据响应格式，从而快速提供 Mock 接口，加快开发进度；
• 9 、在线测试：支持在线对 API 进行测试并保存测试数据，提供接口测试效率；

6.12 版本 V1.0.1 特性（ Coding ）

• 1 、项目权限：支持对项目设置权限，拥有权限才允许操作项目中 API ；

TODO LIST

• 1 、项目权限：支持对项目设置权限，拥有权限才允许操作项目中 API ；
• 2 、 API 历史版本：支持对 API 修改历史版本进行对比，版本回溯等操作；

七、其他

7.1 报告问题

XXL-API 托管在 Github 上，如有问题可在 ISSUES 上提问，也可以加入上文技术交流群；

7.2 接入登记（登记仅为了推广，产品开源免费）

更多接入公司，欢迎在 github 登记

---

支持的话可以扫一扫，支持 XXL 系列 的建设。