《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進行測試並保存測試數據，提供接口測試效率；
- 10、權限控制：支持以業務線為維度進行用戶權限控制，分配權限才允許操作業務線下項目接口和數據類型，否則僅允許查看；
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 初始化“API數據庫”
請下載項目源碼並解壓，獲取 "初始化SQL腳本"，腳本位置：
/xxl-api/doc/db/xxl-api-mysql.sql
2.2 編譯源碼
解壓源碼,按照maven格式將源碼導入IDE, 使用maven進行編譯即可，源碼結構如下：
- xxl-api
- doc
- xxl-api-admin ：API管理中心項目；
2.3 配置JDBC連接
在以下項目文件中設置應用的JDBC連接；
/xxl-api/xxl-api-admin/src/main/resources/xxl-api.properties
2.4 部署
部署運行 "xxl-api-admin" 后，即可訪問：
2.5 集群(可選)
API管理中心支持集群部署，提升系統可用性。
集群部署時，保持各項目JDBC配置一致即可；
三、項目管理
系統中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屬性說明：
基礎信息：
URL：接口請求的URL地址，注意此處為相對地址，根地址從所屬項目的根地址屬性上獲取；
分組：接口所屬的分組；
Method：請求方法，如POST、GET等；
接口狀態：接口的狀態，在接口列表中，啟用狀態接口用綠色圓圈標識，維護狀態接口用黃色圓圈標識，廢棄狀態接口用灰色圓圈標識；
接口名稱：接口的名稱；
請求頭部：同一接口支持設置多個請求頭部；
頭部標簽：請求頭部的類型，如Accept-Encoding；
頭部內容：請求頭部的值，如Accept-Encoding頭部標簽對應的值UTF-8；
請求參數：同一接口支持設置多個請求參數；
參數：參數的名稱；
說明：參數的說明；
類型：該參數的數據類型，如String；
是否必填：該參數是否必填；
響應結果：分別支持設置 "成功響應結果" 和 "失敗響應結果"，作為接口響應數據的參考；
響應數據類型(MIME)：響應結果類型，如JSON、XML等；
響應結果數據：響應結果的數據，如響應結果類型為JSON時可設置響應結果數據為一段JSON數據；
響應數據類型：可綁定數據結構，直觀查看接口的響應數據的格式化信息。
接口備注：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歷史"模塊，點擊測試歷史記錄右側的"刪除"按鈕可刪除本條記錄；
五、數據結構管理
支持維護格式化的數據結構，更加直觀方便的查看數據信息。
接口響應數據支持綁定數據結構，從而更加直觀查看接口的響應數據的格式化信息。
數據結構屬性支持嵌套引用，也支持被復用。
六、用戶管理
系統提供兩種用戶角色：
- 管理員：擁有系統所有權限；
- 普通用戶：默認只擁有項目接口和數據類型的只讀權限，被分配業務線權限后，才允許操作業務線下項目和接口等；
管理員角色登陸之后，可管理系統用戶信息，如添加用戶、設置用戶角色，分配權限等。
不同角色用戶均可以通過右上角 "修改密碼" 功能修改個人登陸密碼；
系統初始化時，默認提供了兩個示例用戶：admin（管理員）、user（普通用戶），密碼默認為 123456；
七、業務線管理
業務線提供兩種功能：
- 分類管理：項目接口歸屬於業務線下，可通過業務線隔離不同的項目接口，方便管理；
- 權限控制：系統以業務線為維度進行權限控制，用戶只有擁有業務線權限，才允許操作業務線下項目接口，否則只允許查看；
系統初始化時，默認一個業務線 "默認業務線"，可以根據情況調整；
八、版本更新日志
8.1 版本 V1.0.0，新特性[2017-04-05]
- 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進行測試並保存測試數據，提供接口測試效率；
8.2 版本 V1.1.0 特性[2018-03-20]
- 1、新增 "業務線" 模塊，針對項目以業務線為粒度進行分類管理；
- 2、新增 "數據類型" 模塊：系統支持錄入數據類型，數據類型支持嵌套，每個API只需要綁定一個數據類型，不需要單獨執行響應數據參數；
- 3、權限控制：支持以業務線為維度進行用戶權限控制，分配權限才允許操作業務線下項目接口和數據類型，否則僅允許查看；
- 4、項目新增屬性"業務線"；項目列表支持通過"業務線"條件查詢；
- 5、接口新增屬性 "響應數據類型" 屬性，通過綁定 "數據類型" 格式化描述接口響應數據結構；
- 6、項目內API搜索關鍵字改為URL，更加貼合用戶需求；
- 7、新增在線修改密碼功能；
- 8、登陸Token與用戶密碼均進行md5加密，提升系統安全性；
- 9、項目maven依賴升級；
- 10、UI交互優化，列表自適應性優化；
- 11、底層代碼重構；
- 12、登陸Cookie啟用HttpOnly；
- 13、彈框插件改為使用Layui；
- 14、AdminLTE版本升級；
- 15、接口測試用例優化，支持存儲接口Method與URL數據；
- 16、接口在線測試時，Get請求URL轉換問題修復；
8.3 版本 V1.1.1 特性[2018-10-26]
- 1、接口"成功/失敗響應結果"支持JSON格式化校驗與展示，方便數據查看；
- 2、項目遷移至 springboot 版本；
- 3、docker支持：提供 Dockerfile 方便快速構建docker鏡像；
- 4、項目下存在接口時拒絕刪除，防止數據誤刪除；
- 5、接口分組刪除問題修復；
- 6、接口在線測試功能對於響應狀態碼為302的請求未能正確展示“Location”問題修復；
8.4 版本 V1.1.2 特性[迭代中]
- 1、【ING】API導出為PDF；
- 2、【ING】支持swagger、postman等格式接口數據導入；
TODO LIST
- 1、請求參數，除常規form之外，支持選擇RequestBody方式，傳遞Json、XML和文本等數據；
- 2、API歷史版本：支持對API修改歷史版本進行對比，版本回溯等操作；
- 3、彈框插件優化：考慮第三方插件；
- 4、支持接口簽名，sign邏輯；
- 5、API響應結果對象管理；
- 6、支持設置RequestBody類型，raw類型參數；
- 7、擁有人、管理員才允許刪除；記錄修改歷史；
- 8、項目權限：支持對項目設置權限，擁有權限才允許操作項目中API；
- 9、根據URL全站匹配API；
- 10、數據類型，代碼生成
- 11、配合xxl-web，實現線上Mocker，支持根據mock-uuid，對調用進行自動mock；
- 12、配合xxl-web，實現根據代碼代碼自動生成api文檔並導入xxl-api管理平台；
- 13、支持Restful類型接口，如 GET /job/{id}/detail ，其中{id}在接口測試時支持動態變化；
- 14、接口歷史版本功能，記錄接口操作變更歷史；
- 15、支持 https 類型接口在線測試，處理接口證書問題；
- 16、請求頭部，除了支持下拉框外，支持手動填寫；
- 17、簡化測試頁，支持Select方式選擇接口，自動填充接口數據並測試；
- 18、接口綁定數據類型時，支持指定標准格式（code、msg、data）；支持自動生成完整數據接口；
- 19、接口數據類型，自動生成Mock數據，提供Runpath接口根據接口地址自動匹配接口生成Mock數據；
- 20、可配置參數支持拖動改變順序；
- 21、接口快速搜索功能；
- 22、Mock添加說明字段；
- 23、權限進一步整理優化；項目支持設置公開、私有；
九、其他
9.1 項目貢獻
歡迎參與項目貢獻！比如提交PR修一個bug，或者新建 Issue 討論新特性或者變更。
9.2 用戶接入登記
更多接入的公司，歡迎在 登記地址 登記，登記僅僅為了產品推廣。
9.3 開源協議和版權
產品開源免費，並且將持續提供免費的社區技術支持。個人或企業內部可自由的接入和使用。
- Licensed under the GNU General Public License (GPL) v3.
- Copyright (c) 2015-present, xuxueli.
捐贈
無論金額多少都足夠表達您這份心意，非常感謝 ：） 前往捐贈