《API管理平臺XXL-API》
1、簡介
1.1 概述
XXL-API 是一個強大易用的API管理平臺,提供API的"管理"、"文檔"、"Mock"和"測試"等功能。現已開放源代碼,開箱即用。html
1.2 特性
- 一、極致簡單:交互簡潔,一分鐘上手;
- 二、項目隔離:API以項目爲維度進行拆分隔離;
- 三、分組管理:單個項目內的API支持自定義分組進行管理;
- 四、標記星級:支持標註API星級,標記後優先展現;
- 五、API管理:建立、更新和刪除API;
- 六、API屬性完善:支持設置豐富的API屬性如:API狀態、請求方法、請求URL、請求頭部、請求參數、響應結果、響應結果格式、響應結果參數、API備註等等;
- 七、markdown:支持爲API添加markdown格式的備註信息;
- 八、Mock:支持爲API定義Mock數據並制定數據響應格式,從而快速提供Mock接口,加快開發進度;
- 九、在線測試:支持在線對API進行測試並保存測試數據,提供接口測試效率;
- 十、權限控制:支持以業務線爲維度進行用戶權限控制,分配權限才容許操做業務線下項目接口和數據類型,不然僅容許查看;
1.3 下載
文檔地址
源碼倉庫地址
技術交流
1.4 環境
- Servlet/JSP Spec:3.0/2.2
- JDK:1.7+
- Tomcat:7+/Jetty8+
- Mysql:5.6+
- Maven:3+
2、快速部署
2.1 初始化「API數據庫」
請下載項目源碼並解壓,獲取 "初始化SQL腳本",腳本位置:mysql
/xxl-api/doc/db/xxl-api-mysql.sql
2.2 編譯源碼
解壓源碼,按照maven格式將源碼導入IDE, 使用maven進行編譯便可,源碼結構以下:git
- xxl-api
- doc
- xxl-api-admin :API管理中心項目;
2.3 配置JDBC鏈接
在如下項目文件中設置應用的JDBC鏈接;github
/xxl-api/xxl-api-admin/src/main/resources/xxl-api.properties
2.4 部署
部署運行 "xxl-api-admin" 後,便可訪問:web
2.5 集羣(可選)
API管理中心支持集羣部署,提高系統可用性。spring
集羣部署時,保持各項目JDBC配置一致便可;sql
3、項目管理
系統中API以項目爲單位進行管理,所以首先須要管理項目;項目管理界面以下圖所示;docker
3.1 新建項目
進入項目管理界面,點擊右側"+新增項目"按鈕可新建項目,以下圖所示:數據庫
項目屬性說明:api
業務線:所屬業務線
項目名稱:項目的名稱;
項目描述:項目的描述信息;
根地址(線上):項目線上環境根地址,項目中的API共用該根地址;
根地址(預發佈):項目預發佈環境根地址;
根地址(測試):項目測試環境根地址;
3.2 更新項目
進入項目管理界面,點擊項目右側的"編輯"按鈕可更新項目信息;
3.3 刪除項目
進入項目管理界面,點擊項目右側的"刪除"按鈕可刪除項目信息;注意,項目中存在API時不容許刪除;
4、API管理
在項目管理界面,點擊項目右側的"進入項目"按鈕,可進入接口管理界面:
4.1 API分組管理
以下圖,點擊"左側接口分組區域"右上角的"+"按鈕,可新增AIP接口分組;(點擊"所有"將會展現項目中全部分組下的接口;"默認分組"爲系統分組,不容許刪除;)
接口分組屬性說明:
分組名稱:分組的名稱
分組排序:分組的排序順序,數字類型,值越小越靠前;
在"左側接口分組區域",點擊對應的API分組,右側將會展現該分組下API接口列表;點擊接口列表頂部的"編輯分組"按鈕(新增的API分組纔會有該功能),可修改API分組信息;
在"左側接口分組區域",點擊對應的API分組,右側將會展現該分組下API接口列表;點擊接口列表頂部的"刪除分組"按鈕(新增的API分組纔會有該功能),可修改API分組信息;
4.2 API管理
以下圖,在API接口管理界面,點擊接口列表頂部的"新增接口"按鈕,可進入新增接口界面;
在新增接口界面,以下圖所示,能夠設置接口的API狀態、請求方法、請求URL、請求頭部、請求參數、響應結果、響應結果格式、響應結果參數、API備註等等信息;
API屬性說明:
基礎信息:
URL:接口請求的URL地址,注意此處爲相對地址,根地址從所屬項目的根地址屬性上獲取;
分組:接口所屬的分組;
Method:請求方法,如POST、GET等;
接口狀態:接口的狀態,在接口列表中,啓用狀態接口用綠色圓圈標識,維護狀態接口用黃色圓圈標識,廢棄狀態接口用灰色圓圈標識;
接口名稱:接口的名稱;
請求頭部:同一接口支持設置多個請求頭部;
頭部標籤:請求頭部的類型,如Accept-Encoding;
頭部內容:請求頭部的值,如Accept-Encoding頭部標籤對應的值UTF-8;
請求參數:同一接口支持設置多個請求參數;
參數:參數的名稱;
說明:參數的說明;
類型:該參數的數據類型,如String;
是否必填:該參數是否必填;
響應結果:分別支持設置 "成功響應結果" 和 "失敗響應結果",做爲接口響應數據的參考;
響應數據類型(MIME):響應結果類型,如JSON、XML等;
響應結果數據:響應結果的數據,如響應結果類型爲JSON時可設置響應結果數據爲一段JSON數據;
響應數據類型:可綁定數據結構,直觀查看接口的響應數據的格式化信息。
接口備註:markdown方式的接口備註;
在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鏈接,訪問該鏈接將會按照設置的數據類型如JSON返回對應格式的Mock數據,以下圖所示;
4.4 API-測試
- API-測試
進入"接口詳情頁",點擊"Test歷史"模塊右上角的"+接口測試"按鈕,可進入"接口測試界面",
該界面將會自動初始化接口URL(測試界面支持選擇運行環境,將會自動生成不一樣環境的完整URL鏈接)和參數等信息。
只須要填寫測試的參數值,點擊下方"運行"按鈕,便可發起一次接口請求,請求結果將會在下方顯示出來:
在"接口測試界面",在進行接口測試後, 點擊下方"保存"按鈕將會把本次測試數據(接口URL,測試參數等信息)保存下來。
在"接口詳情頁"的"Test歷史"模塊可查看全部的接口測試歷史記錄。點擊一次測試記錄右側的"運行"按鈕,將會進入到本次測試記錄對應的接口測試界面,還原當時測試時使用的測試數據;
在"接口詳情頁"的"Test歷史"模塊,點擊測試歷史記錄右側的"刪除"按鈕可刪除本條記錄;
5、數據結構管理
支持維護格式化的數據結構,更加直觀方便的查看數據信息。
接口響應數據支持綁定數據結構,從而更加直觀查看接口的響應數據的格式化信息。
數據結構屬性支持嵌套引用,也支持被複用。
6、用戶管理
系統提供兩種用戶角色:
- 管理員:擁有系統全部權限;
- 普通用戶:默認只擁有項目接口和數據類型的只讀權限,被分配業務線權限後,才容許操做業務線下項目和接口等;
管理員角色登錄以後,可管理系統用戶信息,如添加用戶、設置用戶角色,分配權限等。
不一樣角色用戶都可以經過右上角 "修改密碼" 功能修改我的登錄密碼;
系統初始化時,默認提供了兩個示例用戶:admin(管理員)、user(普通用戶),密碼默認爲 123456;
7、業務線管理
業務線提供兩種功能:
- 分類管理:項目接口歸屬於業務線下,可經過業務線隔離不一樣的項目接口,方便管理;
- 權限控制:系統以業務線爲維度進行權限控制,用戶只有擁有業務線權限,才容許操做業務線下項目接口,不然只容許查看;
系統初始化時,默認一個業務線 "默認業務線",能夠根據狀況調整;
8、版本更新日誌
8.1 版本 V1.0.0,新特性[2017-04-05]
- 一、極致簡單:交互簡潔,一分鐘上手;
- 二、項目隔離:API以項目爲維度進行拆分隔離;
- 三、分組管理:單個項目內的API支持自定義分組進行管理;
- 四、標記星級:支持標註API星級,標記後優先展現;
- 五、API管理:建立、更新和刪除API;
- 六、API屬性完善:支持設置豐富的API屬性如:API狀態、請求方法、請求URL、請求頭部、請求參數、響應結果、響應結果格式、響應結果參數、API備註等等;
- 七、markdown:支持爲API添加markdown格式的備註信息;
- 八、Mock:支持爲API定義Mock數據並制定數據響應格式,從而快速提供Mock接口,加快開發進度;
- 九、在線測試:支持在線對API進行測試並保存測試數據,提供接口測試效率;
8.2 版本 V1.1.0 特性[2018-03-20]
- 一、新增 "業務線" 模塊,針對項目以業務線爲粒度進行分類管理;
- 二、新增 "數據類型" 模塊:系統支持錄入數據類型,數據類型支持嵌套,每一個API只須要綁定一個數據類型,不須要單獨執行響應數據參數;
- 三、權限控制:支持以業務線爲維度進行用戶權限控制,分配權限才容許操做業務線下項目接口和數據類型,不然僅容許查看;
- 四、項目新增屬性"業務線";項目列表支持經過"業務線"條件查詢;
- 五、接口新增屬性 "響應數據類型" 屬性,經過綁定 "數據類型" 格式化描述接口響應數據結構;
- 六、項目內API搜索關鍵字改成URL,更加貼合用戶需求;
- 七、新增在線修改密碼功能;
- 八、登錄Token與用戶密碼均進行md5加密,提高系統安全性;
- 九、項目maven依賴升級;
- 十、UI交互優化,列表自適應性優化;
- 十一、底層代碼重構;
- 十二、登錄Cookie啓用HttpOnly;
- 1三、彈框插件改成使用Layui;
- 1四、AdminLTE版本升級;
- 1五、接口測試用例優化,支持存儲接口Method與URL數據;
- 1六、接口在線測試時,Get請求URL轉換問題修復;
8.3 版本 V1.1.1 特性[2018-10-26]
- 一、接口"成功/失敗響應結果"支持JSON格式化校驗與展現,方便數據查看;
- 二、項目遷移至 springboot 版本;
- 三、docker支持:提供 Dockerfile 方便快速構建docker鏡像;
- 四、項目下存在接口時拒絕刪除,防止數據誤刪除;
- 五、接口分組刪除問題修復;
- 六、接口在線測試功能對於響應狀態碼爲302的請求未能正確展現「Location」問題修復;
8.4 版本 V1.1.2 特性[迭代中]
- 一、【ING】API導出爲PDF;
- 二、【ING】支持swagger、postman等格式接口數據導入;
TODO LIST
- 一、請求參數,除常規form以外,支持選擇RequestBody方式,傳遞Json、XML和文本等數據;
- 二、API歷史版本:支持對API修改歷史版本進行對比,版本回溯等操做;
- 三、彈框插件優化:考慮第三方插件;
- 四、支持接口簽名,sign邏輯;
- 五、API響應結果對象管理;
- 六、支持設置RequestBody類型,raw類型參數;
- 七、擁有人、管理員才容許刪除;記錄修改歷史;
- 八、項目權限:支持對項目設置權限,擁有權限才容許操做項目中API;
- 九、根據URL全站匹配API;
- 十、數據類型,代碼生成
- 十一、配合xxl-web,實現線上Mocker,支持根據mock-uuid,對調用進行自動mock;
- 十二、配合xxl-web,實現根據代碼代碼自動生成api文檔並導入xxl-api管理平臺;
- 1三、支持Restful類型接口,如 GET /job/{id}/detail ,其中{id}在接口測試時支持動態變化;
- 1四、接口歷史版本功能,記錄接口操做變動歷史;
- 1五、支持 https 類型接口在線測試,處理接口證書問題;
- 1六、請求頭部,除了支持下拉框外,支持手動填寫;
- 1七、簡化測試頁,支持Select方式選擇接口,自動填充接口數據並測試;
- 1八、接口綁定數據類型時,支持指定標準格式(code、msg、data);支持自動生成完整數據接口;
- 1九、接口數據類型,自動生成Mock數據,提供Runpath接口根據接口地址自動匹配接口生成Mock數據;
- 20、可配置參數支持拖動改變順序;
- 2一、接口快速搜索功能;
- 2二、Mock添加說明字段;
- 2三、權限進一步整理優化;項目支持設置公開、私有;
9、其餘
9.1 項目貢獻
歡迎參與項目貢獻!好比提交PR修一個bug,或者新建 Issue 討論新特性或者變動。
9.2 用戶接入登記
更多接入的公司,歡迎在 登記地址 登記,登記僅僅爲了產品推廣。
9.3 開源協議和版權
產品開源免費,而且將持續提供免費的社區技術支持。我的或企業內部可自由的接入和使用。
- Licensed under the GNU General Public License (GPL) v3.
- Copyright (c) 2015-present, xuxueli.
捐贈
不管金額多少都足夠表達您這份心意,很是感謝 :) 前往捐贈