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 下載

文檔地址

中文文檔

源碼倉庫地址

源碼倉庫地址	Release Download
https://github.com/xuxueli/xxl-api	Download
http://gitee.com/xuxueli0323/xxl-api	Download

技術交流

社區交流

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、新增用戶

進入用戶管理界面，點擊右上角"+新增用戶"按鈕，可添加用戶信息；

用戶屬性說明：

登錄賬號：用戶的登錄賬號；
登錄密碼：用戶的登錄密碼；
用戶類型：
    普通用戶：只允許操作公開項目，或者自己擁有項目權限的私有項目；
    超級管理員：擁有所有項目的操作權限；
真實姓名：用戶的真實姓名；

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、新增"業務線"管理功能，針對項目以業務線爲粒度進行分類管理，該功能僅向管理員開放；
2、項目新增"業務線"屬性；項目列表支持通過"業務線"條件查詢；
3、項目內API搜索關鍵字改爲URL，更加貼合用戶需求；
4、設計實現API "響應數據類型" 模塊，"響應數據類型"不僅可以被多個API複用，而且支持數據類型嵌套；
5、"數據類型"功能：系統支持錄入數據類型，數據類型支持嵌套，每個API只需要綁定一個數據類型，不需要單獨執行響應數據參數；
6、請求參數，除常規form之外，支持選擇RequestBody方式，傳遞Json、XML和文本等數據；

TODO LIST

1、項目權限：支持對項目設置權限，擁有權限才允許操作項目中API；
2、API歷史版本：支持對API修改歷史版本進行對比，版本回溯等操作；
3、彈框插件優化：考慮第三方插件；
4、支持接口簽名，sign邏輯；
5、API導出爲HTML或者PDF；
6、API響應結果對象管理；
7、支持設置RequestBody類型參數；
8、擁有人、管理員才允許刪除；記錄修改歷史；
9、項目權限：支持對項目設置權限，擁有權限才允許操作項目中API；
10、根據URL全站匹配API；
11、數據類型，代碼生成
12、配合xxl-web，實現線上Mocker，支持根據mock-uuid，對調用進行自動mock；
13、配合xxl-web，實現根據代碼代碼自動生成api文檔並導入xxl-api管理平臺；
14、支持Restful類型接口；

Licensed under the GNU General Public License (GPL) v3.