《API管理平臺XXL-API》
一、簡介
1.1 概述
XXL-API是一個(gè)簡潔易用API管理平臺，提供API的"管理"、"文檔"、"Mock"和"測試"等功能。現(xiàn)已開放源代碼，開箱即用。
1.2 特性
- 1、極致簡單：交互簡潔，一分鐘上手；
- 2、項(xiàng)目隔離：API以項(xiàng)目為維度進(jìn)行拆分隔離；
- 3、分組管理：單個(gè)項(xiàng)目內(nèi)的API支持自定義分組進(jìn)行管理；
- 4、標(biāo)記星級：支持標(biāo)注API星級，標(biāo)記后優(yōu)先展示；
- 5、API管理：創(chuàng)建、更新和刪除API；
- 6、API屬性完善：支持設(shè)置豐富的API屬性如：API狀態(tài)、請求方法、請求URL、請求頭部、請求參數(shù)、響應(yīng)結(jié)果、響應(yīng)結(jié)果格式、響應(yīng)結(jié)果參數(shù)、API備注等等；
- 7、markdown：支持為API添加markdown格式的備注信息；
- 8、Mock：支持為API定義Mock數(shù)據(jù)并制定數(shù)據(jù)響應(yīng)格式，從而快速提供Mock接口，加快開發(fā)進(jìn)度；
- 9、在線測試：支持在線對API進(jìn)行測試并保存測試數(shù)據(jù)，提供接口測試效率；
1.3 下載
文檔地址
源碼倉庫地址
| 源碼倉庫地址 | Release Download |
|---|---|
| https://github.com/xuxueli/xxl-api | Download |
| http://git.oschina.net/xuxueli0323/xxl-api | Download |
技術(shù)交流
1.4 環(huán)境
- Servlet/JSP Spec：3.0/2.2
- JDK：1.7+
- Tomcat：7+/Jetty8+
- Mysql：5.6+
- Maven：3+
二、快速部署
2.1 初始化“調(diào)度數(shù)據(jù)庫”
請下載項(xiàng)目源碼并解壓，獲取 "初始化SQL腳本"，腳本位置：
/xxl-api/db/xxl-api-mysql.sql
2.2 編譯源碼
解壓源碼,按照maven格式將源碼導(dǎo)入IDE, 使用maven進(jìn)行編譯即可，源碼結(jié)構(gòu)如下圖所示：
2.3 配置JDBC連接
在以下項(xiàng)目文件中設(shè)置應(yīng)用的JDBC連接；
/xxl-api/xxl-api-admin/src/main/resources/xxl-api.properties
2.4 部署
將應(yīng)用"xxl-api-admin"部署在容器如Tomcat下之后，啟動(dòng)后訪問即可進(jìn)入以下界面：
三、項(xiàng)目管理
系統(tǒng)中API以項(xiàng)目為單位進(jìn)行管理，因此首先需要管理項(xiàng)目；項(xiàng)目管理界面如下圖所示；
3.1 新建項(xiàng)目
進(jìn)入項(xiàng)目管理界面，點(diǎn)擊右側(cè)"+新增項(xiàng)目"按鈕可新建項(xiàng)目，如下圖所示：
項(xiàng)目屬性說明：
項(xiàng)目名稱：項(xiàng)目的名稱；
項(xiàng)目描述：項(xiàng)目的描述信息；
訪問權(quán)限："公開"權(quán)限，表示所有人可操作；"私有"權(quán)限，表示只有管理員或者項(xiàng)目成員可以操作（功能自測中，即將推送）；
跟地址-線上環(huán)境：項(xiàng)目線上環(huán)境跟地址，項(xiàng)目中的API共用該跟地址；
跟地址-預(yù)發(fā)布環(huán)境：項(xiàng)目預(yù)發(fā)布環(huán)境跟地址；
跟地址-測試環(huán)境：項(xiàng)目測試環(huán)境跟地址；
版本：項(xiàng)目的版本信息；
3.2 更新項(xiàng)目
進(jìn)入項(xiàng)目管理界面，點(diǎn)擊項(xiàng)目右側(cè)的"編輯"按鈕可更新項(xiàng)目信息，如下圖所示；
3.3 刪除項(xiàng)目
進(jìn)入項(xiàng)目管理界面，點(diǎn)擊項(xiàng)目右側(cè)的"刪除"按鈕可刪除項(xiàng)目信息；注意，項(xiàng)目中存在API時(shí)不允許刪除；
四、API管理
在項(xiàng)目管理界面，點(diǎn)擊項(xiàng)目右側(cè)的"進(jìn)入項(xiàng)目"按鈕，可進(jìn)入接口管理界面，如下圖所示：
4.1 API分組管理
- 新增API分組
如下圖，點(diǎn)擊"左側(cè)接口分組區(qū)域"右上角的"+"按鈕，可新增AIP接口分組；（點(diǎn)擊"全部"將會展示項(xiàng)目中所有分組下的接口；"默認(rèn)分組"為系統(tǒng)分組，不允許刪除；）
接口分組屬性說明：
分組名稱：分組的名稱
分組排序：分組的排序順序，數(shù)字類型，值越小越靠前；
- 更新API分組
在"左側(cè)接口分組區(qū)域"，點(diǎn)擊對應(yīng)的API分組，右側(cè)將會展示該分組下API接口列表；如下圖，點(diǎn)擊接口列表頂部的"編輯分組"按鈕（新增的API分組才會有該功能），可修改API分組信息；
- 刪除API分組
在"左側(cè)接口分組區(qū)域"，點(diǎn)擊對應(yīng)的API分組，右側(cè)將會展示該分組下API接口列表；點(diǎn)擊接口列表頂部的"刪除分組"按鈕（新增的API分組才會有該功能），可修改API分組信息；
4.2 API管理
- 新增API
如下圖，在API接口管理界面，點(diǎn)擊接口列表頂部的"新增接口"按鈕，可進(jìn)入新增接口界面；
在新增接口界面，如下圖所示，可以設(shè)置接口的API狀態(tài)、請求方法、請求URL、請求頭部、請求參數(shù)、響應(yīng)結(jié)果、響應(yīng)結(jié)果格式、響應(yīng)結(jié)果參數(shù)、API備注等等信息；
API屬性說明：
基礎(chǔ)信息：
接口分組：接口所屬的分組；
接口狀態(tài)：接口的狀態(tài)，在接口列表中，啟用狀態(tài)接口用綠色圓圈標(biāo)識，維護(hù)狀態(tài)接口用黃色圓圈標(biāo)識，廢棄狀態(tài)接口用灰色圓圈標(biāo)識；
請求方法：請求方法，如POST、GET等；
接口URL：接口請求的URL地址，注意此處為相對地址，跟地址從所屬項(xiàng)目的跟地址屬性上獲??；
接口名稱：接口的名稱；
請求頭部：同一接口支持設(shè)置多個(gè)請求頭部；
頭部標(biāo)簽：請求頭部的類型，如Accept-Encoding；
頭部內(nèi)容：請求頭部的數(shù)據(jù)，如Accept-Encoding頭部標(biāo)簽的頭部內(nèi)容UTF-8；
請求參數(shù)：同一接口支持設(shè)置多個(gè)請求參數(shù)；
是否必填：該參數(shù)是否必填；
參數(shù)類型：該參數(shù)的數(shù)據(jù)類型，如STRING；
參數(shù)名稱：參數(shù)的名稱；
參數(shù)說明：參數(shù)的說明；
響應(yīng)結(jié)果：分別支持設(shè)置 "成功響應(yīng)結(jié)果" 和 "失敗響應(yīng)結(jié)果"，作為接口響應(yīng)數(shù)據(jù)的參考；
響應(yīng)數(shù)據(jù)類型(MIME)：響應(yīng)結(jié)果類型，如JSON、XML等；
響應(yīng)結(jié)果數(shù)據(jù)：響應(yīng)結(jié)果的數(shù)據(jù)，如響應(yīng)結(jié)果類型為JSON時(shí)可設(shè)置響應(yīng)結(jié)果數(shù)據(jù)為一段JSON數(shù)據(jù)；
響應(yīng)結(jié)果參數(shù)：對接口"響應(yīng)結(jié)果"中參數(shù)的補(bǔ)充說明，如響應(yīng)結(jié)果類型為JSON時(shí)，可在此處一一列出JSON各個(gè)字段的參數(shù)信息；
是否非空：該參數(shù)是否可能為空；
參數(shù)類型：該參數(shù)的數(shù)據(jù)類型，如STRING；
參數(shù)名稱：參數(shù)的名稱；
參數(shù)說明：參數(shù)的說明；
接口備注：markdown方式的接口備注；
- 更新API
在API接口管理界面，點(diǎn)擊接口右側(cè)的"更新接口圖標(biāo)"按鈕，可進(jìn)入更新接口界面；
- 刪除API
在API接口管理界面，點(diǎn)擊接口右側(cè)的"刪除接口圖標(biāo)"按鈕，可刪除接口數(shù)據(jù)；
4.3 API-Mock
- 新增Mock數(shù)據(jù)
在API接口管理界面，點(diǎn)擊接口名稱，進(jìn)入"接口詳情頁"，在接口詳情頁的"Mock數(shù)據(jù)"模塊右上角點(diǎn)擊"+Mock數(shù)據(jù)"按鈕，可新增Mock數(shù)據(jù)；
Mock數(shù)據(jù)屬性說明：
數(shù)據(jù)類型(MIME)：響應(yīng)結(jié)果類型，如JSON、XML等；
結(jié)果數(shù)據(jù)：響應(yīng)結(jié)果的數(shù)據(jù)，如響應(yīng)結(jié)果類型為JSON時(shí)可設(shè)置響應(yīng)結(jié)果數(shù)據(jù)為一段JSON數(shù)據(jù)；
- 更新Mock數(shù)據(jù)
在"接口詳情頁"的"Mock數(shù)據(jù)"模塊，點(diǎn)擊Mock數(shù)據(jù)列表右側(cè)的"修改"按鈕，可修改Mock數(shù)據(jù)；
- 刪除Mock數(shù)據(jù)
在"接口詳情頁"的"Mock數(shù)據(jù)"模塊，點(diǎn)擊Mock數(shù)據(jù)列表右側(cè)的"刪除"按鈕，可刪除Mock數(shù)據(jù)；
- 運(yùn)行Mock數(shù)據(jù)
在"接口詳情頁"的"Mock數(shù)據(jù)"模塊，點(diǎn)擊Mock數(shù)據(jù)列表右側(cè)的"運(yùn)行"按鈕，可運(yùn)行Mock數(shù)據(jù)；
系統(tǒng)將會為每一條Mock數(shù)據(jù)生成一個(gè)唯一的Mock連接，訪問該連接將會按照設(shè)置的數(shù)據(jù)類型如JSON返回對應(yīng)格式的Mock數(shù)據(jù)，如下圖所示；
4.4 API-測試
- API-測試
進(jìn)入"接口詳情頁"，點(diǎn)擊"Test歷史"模塊右上角的"+接口測試"按鈕，可進(jìn)入"接口測試界面"，
該界面將會自動(dòng)初始化接口URL（測試界面支持選擇運(yùn)行環(huán)境，將會自動(dòng)生成不同環(huán)境的完整URL連接）和參數(shù)等信息。
只需要填寫測試的參數(shù)值，點(diǎn)擊下方"運(yùn)行"按鈕，即可發(fā)起一次接口請求，請求結(jié)果將會在下方顯示出來：
- 保存Test歷史
在"接口測試界面"，在進(jìn)行接口測試后, 點(diǎn)擊下方"保存"按鈕將會把本次測試數(shù)據(jù)（接口URL，測試參數(shù)等信息）保存下來。
在"接口詳情頁"的"Test歷史"模塊可查看所有的接口測試歷史記錄。點(diǎn)擊一次測試記錄右側(cè)的"運(yùn)行"按鈕，將會進(jìn)入到本次測試記錄對應(yīng)的接口測試界面，還原當(dāng)時(shí)測試時(shí)使用的測試數(shù)據(jù)；
- 刪除Test歷史
在"接口詳情頁"的"Test歷史"模塊，點(diǎn)擊測試歷史記錄右側(cè)的"刪除"按鈕可刪除本條記錄；
五、用戶管理
5.1、新增用戶
進(jìn)入用戶管理界面，點(diǎn)擊右上角"+新增用戶"按鈕，可添加用戶信息；
用戶屬性說明：
登錄賬號：用戶的登錄賬號；
登錄密碼：用戶的登錄密碼；
用戶類型：
普通用戶：只允許操作公開項(xiàng)目，或者自己擁有項(xiàng)目權(quán)限的私有項(xiàng)目；
超級管理員：擁有所有項(xiàng)目的操作權(quán)限；
真實(shí)姓名：用戶的真實(shí)姓名；
5.2、更新用戶
進(jìn)入用戶管理界面，點(diǎn)擊用戶列表頁中用戶右側(cè)的"編輯"按鈕可編譯用戶信息；
5.3、刪除用戶
進(jìn)入用戶管理界面，點(diǎn)擊用戶列表頁中用戶右側(cè)的"刪除"按鈕可刪除用戶信息；
六、版本更新日志
略
七、其他
7.1 項(xiàng)目貢獻(xiàn)
歡迎參與項(xiàng)目貢獻(xiàn)！比如提交PR修復(fù)一個(gè)bug，或者新建 Issue 討論新特性或者變更。
7.2 用戶接入登記
更多接入的公司，歡迎在 登記地址 登記，登記僅僅為了產(chǎn)品推廣。
7.3 開源協(xié)議和版權(quán)
產(chǎn)品開源免費(fèi)，并且將持續(xù)提供免費(fèi)的社區(qū)技術(shù)支持。個(gè)人或企業(yè)內(nèi)部可自由的接入和使用。
- Licensed under the GNU General Public License (GPL) v3.
- Copyright (c) 2015-present, xuxueli.
捐贈
無論金額多少都足夠表達(dá)您這份心意，非常感謝 ：） XXL系列捐贈記錄
