API管理平臺XXL-API

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

文檔地址

源碼倉庫地址

源碼倉庫地址 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、快速部署

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分組管理

  • 新增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歷史"模塊,點擊測試歷史記錄右側的"刪除"按鈕可刪除本條記錄;

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.

捐贈

不管金額多少都足夠表達您這份心意,很是感謝 :) 前往捐贈

相關文章
相關標籤/搜索