《 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 仓库同步发布最新代码)

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

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

群 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 登记

API 管理平台 XXL-API