《API管理平臺XXL-API》
一大咱、簡介
1.1 概述
XXL-API是一個簡潔易用API管理平臺咆霜，提供API的"管理"、"文檔"忆矛、"Mock"和"測試"等功能〔於祝現(xiàn)已開放源代碼，開箱即用催训。
1.2 特性
- 1洽议、極致簡單：交互簡潔，一分鐘上手漫拭；
- 2亚兄、項目隔離：API以項目為維度進行拆分隔離；
- 3采驻、分組管理：單個項目內(nèi)的API支持自定義分組進行管理审胚；
- 4、標記星級：支持標注API星級礼旅，標記后優(yōu)先展示膳叨；
- 5、API管理：創(chuàng)建痘系、更新和刪除API菲嘴；
- 6、API屬性完善：支持設置豐富的API屬性如：API狀態(tài)汰翠、請求方法龄坪、請求URL、請求頭部复唤、請求參數(shù)健田、響應結(jié)果、響應結(jié)果格式佛纫、響應結(jié)果參數(shù)妓局、API備注等等；
- 7呈宇、markdown：支持為API添加markdown格式的備注信息跟磨；
- 8、Mock：支持為API定義Mock數(shù)據(jù)并制定數(shù)據(jù)響應格式攒盈，從而快速提供Mock接口抵拘，加快開發(fā)進度；
- 9型豁、在線測試：支持在線對API進行測試并保存測試數(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ù)庫”
請下載項目源碼并解壓充尉，獲取 "初始化SQL腳本"飘言，腳本位置：
/xxl-api/db/xxl-api-mysql.sql
2.2 編譯源碼
解壓源碼,按照maven格式將源碼導入IDE, 使用maven進行編譯即可，源碼結(jié)構(gòu)如下圖所示：
2.3 配置JDBC連接
在以下項目文件中設置應用的JDBC連接驼侠；
/xxl-api/xxl-api-admin/src/main/resources/xxl-api.properties
2.4 部署
將應用"xxl-api-admin"部署在容器如Tomcat下之后姿鸿，啟動后訪問即可進入以下界面：
三、項目管理
系統(tǒng)中API以項目為單位進行管理倒源，因此首先需要管理項目苛预；項目管理界面如下圖所示；
3.1 新建項目
進入項目管理界面笋熬，點擊右側(cè)"+新增項目"按鈕可新建項目热某，如下圖所示：
項目屬性說明：
項目名稱：項目的名稱；
項目描述：項目的描述信息胳螟；
訪問權(quán)限："公開"權(quán)限昔馋，表示所有人可操作；"私有"權(quán)限糖耸，表示只有管理員或者項目成員可以操作（功能自測中秘遏，即將推送）；
跟地址-線上環(huán)境：項目線上環(huán)境跟地址嘉竟，項目中的API共用該跟地址邦危；
跟地址-預發(fā)布環(huán)境：項目預發(fā)布環(huán)境跟地址；
跟地址-測試環(huán)境：項目測試環(huán)境跟地址周拐；
版本：項目的版本信息铡俐；
3.2 更新項目
進入項目管理界面凰兑，點擊項目右側(cè)的"編輯"按鈕可更新項目信息妥粟，如下圖所示；
3.3 刪除項目
進入項目管理界面吏够，點擊項目右側(cè)的"刪除"按鈕可刪除項目信息勾给；注意，項目中存在API時不允許刪除锅知；
四播急、API管理
在項目管理界面，點擊項目右側(cè)的"進入項目"按鈕售睹，可進入接口管理界面桩警，如下圖所示：
4.1 API分組管理
- 新增API分組
如下圖，點擊"左側(cè)接口分組區(qū)域"右上角的"+"按鈕昌妹，可新增AIP接口分組捶枢；（點擊"全部"將會展示項目中所有分組下的接口握截；"默認分組"為系統(tǒng)分組，不允許刪除烂叔；）
接口分組屬性說明：
分組名稱：分組的名稱
分組排序：分組的排序順序谨胞，數(shù)字類型，值越小越靠前蒜鸡；
- 更新API分組
在"左側(cè)接口分組區(qū)域"胯努，點擊對應的API分組，右側(cè)將會展示該分組下API接口列表逢防；如下圖叶沛，點擊接口列表頂部的"編輯分組"按鈕（新增的API分組才會有該功能），可修改API分組信息胞四；
- 刪除API分組
在"左側(cè)接口分組區(qū)域"恬汁，點擊對應的API分組，右側(cè)將會展示該分組下API接口列表辜伟；點擊接口列表頂部的"刪除分組"按鈕（新增的API分組才會有該功能）氓侧，可修改API分組信息；
4.2 API管理
- 新增API
如下圖导狡，在API接口管理界面约巷，點擊接口列表頂部的"新增接口"按鈕，可進入新增接口界面旱捧；
在新增接口界面独郎，如下圖所示，可以設置接口的API狀態(tài)枚赡、請求方法氓癌、請求URL、請求頭部贫橙、請求參數(shù)贪婉、響應結(jié)果、響應結(jié)果格式卢肃、響應結(jié)果參數(shù)疲迂、API備注等等信息；
API屬性說明：
基礎信息：
接口分組：接口所屬的分組莫湘；
接口狀態(tài)：接口的狀態(tài)尤蒿，在接口列表中，啟用狀態(tài)接口用綠色圓圈標識幅垮，維護狀態(tài)接口用黃色圓圈標識腰池，廢棄狀態(tài)接口用灰色圓圈標識；
請求方法：請求方法，如POST示弓、GET等演怎；
接口URL：接口請求的URL地址，注意此處為相對地址避乏，跟地址從所屬項目的跟地址屬性上獲纫；
接口名稱：接口的名稱拍皮；
請求頭部：同一接口支持設置多個請求頭部歹叮；
頭部標簽：請求頭部的類型，如Accept-Encoding铆帽；
頭部內(nèi)容：請求頭部的數(shù)據(jù)咆耿，如Accept-Encoding頭部標簽的頭部內(nèi)容UTF-8；
請求參數(shù)：同一接口支持設置多個請求參數(shù)爹橱；
是否必填：該參數(shù)是否必填萨螺；
參數(shù)類型：該參數(shù)的數(shù)據(jù)類型，如STRING愧驱；
參數(shù)名稱：參數(shù)的名稱慰技；
參數(shù)說明：參數(shù)的說明；
響應結(jié)果：分別支持設置 "成功響應結(jié)果" 和 "失敗響應結(jié)果"组砚，作為接口響應數(shù)據(jù)的參考吻商；
響應數(shù)據(jù)類型(MIME)：響應結(jié)果類型，如JSON糟红、XML等艾帐；
響應結(jié)果數(shù)據(jù)：響應結(jié)果的數(shù)據(jù)，如響應結(jié)果類型為JSON時可設置響應結(jié)果數(shù)據(jù)為一段JSON數(shù)據(jù)盆偿；
響應結(jié)果參數(shù)：對接口"響應結(jié)果"中參數(shù)的補充說明柒爸，如響應結(jié)果類型為JSON時，可在此處一一列出JSON各個字段的參數(shù)信息事扭；
是否非空：該參數(shù)是否可能為空捎稚；
參數(shù)類型：該參數(shù)的數(shù)據(jù)類型，如STRING句旱；
參數(shù)名稱：參數(shù)的名稱阳藻；
參數(shù)說明：參數(shù)的說明晰奖；
接口備注：markdown方式的接口備注谈撒；
- 更新API
在API接口管理界面，點擊接口右側(cè)的"更新接口圖標"按鈕匾南，可進入更新接口界面啃匿；
- 刪除API
在API接口管理界面，點擊接口右側(cè)的"刪除接口圖標"按鈕，可刪除接口數(shù)據(jù)溯乒；
4.3 API-Mock
- 新增Mock數(shù)據(jù)
在API接口管理界面夹厌，點擊接口名稱，進入"接口詳情頁"裆悄，在接口詳情頁的"Mock數(shù)據(jù)"模塊右上角點擊"+Mock數(shù)據(jù)"按鈕矛纹，可新增Mock數(shù)據(jù)；
Mock數(shù)據(jù)屬性說明：
數(shù)據(jù)類型(MIME)：響應結(jié)果類型光稼，如JSON或南、XML等；
結(jié)果數(shù)據(jù)：響應結(jié)果的數(shù)據(jù)艾君，如響應結(jié)果類型為JSON時可設置響應結(jié)果數(shù)據(jù)為一段JSON數(shù)據(jù)采够；
- 更新Mock數(shù)據(jù)
在"接口詳情頁"的"Mock數(shù)據(jù)"模塊，點擊Mock數(shù)據(jù)列表右側(cè)的"修改"按鈕冰垄，可修改Mock數(shù)據(jù)蹬癌；
- 刪除Mock數(shù)據(jù)
在"接口詳情頁"的"Mock數(shù)據(jù)"模塊，點擊Mock數(shù)據(jù)列表右側(cè)的"刪除"按鈕虹茶，可刪除Mock數(shù)據(jù)逝薪；
- 運行Mock數(shù)據(jù)
在"接口詳情頁"的"Mock數(shù)據(jù)"模塊，點擊Mock數(shù)據(jù)列表右側(cè)的"運行"按鈕蝴罪，可運行Mock數(shù)據(jù)翼闽；
系統(tǒng)將會為每一條Mock數(shù)據(jù)生成一個唯一的Mock連接，訪問該連接將會按照設置的數(shù)據(jù)類型如JSON返回對應格式的Mock數(shù)據(jù)洲炊，如下圖所示感局；
4.4 API-測試
- API-測試
進入"接口詳情頁"，點擊"Test歷史"模塊右上角的"+接口測試"按鈕暂衡，可進入"接口測試界面"询微，
該界面將會自動初始化接口URL（測試界面支持選擇運行環(huán)境，將會自動生成不同環(huán)境的完整URL連接）和參數(shù)等信息狂巢。
只需要填寫測試的參數(shù)值撑毛，點擊下方"運行"按鈕，即可發(fā)起一次接口請求唧领，請求結(jié)果將會在下方顯示出來：
- 保存Test歷史
在"接口測試界面"藻雌，在進行接口測試后, 點擊下方"保存"按鈕將會把本次測試數(shù)據(jù)（接口URL，測試參數(shù)等信息）保存下來斩个。
在"接口詳情頁"的"Test歷史"模塊可查看所有的接口測試歷史記錄胯杭。點擊一次測試記錄右側(cè)的"運行"按鈕，將會進入到本次測試記錄對應的接口測試界面受啥，還原當時測試時使用的測試數(shù)據(jù)做个；
- 刪除Test歷史
在"接口詳情頁"的"Test歷史"模塊鸽心，點擊測試歷史記錄右側(cè)的"刪除"按鈕可刪除本條記錄顽频；
五省骂、用戶管理
5.1、新增用戶
進入用戶管理界面，點擊右上角"+新增用戶"按鈕，可添加用戶信息讽膏；
用戶屬性說明：
登錄賬號：用戶的登錄賬號垄潮；
登錄密碼：用戶的登錄密碼逢勾；
用戶類型：
普通用戶：只允許操作公開項目盟迟，或者自己擁有項目權(quán)限的私有項目迫皱；
超級管理員：擁有所有項目的操作權(quán)限；
真實姓名：用戶的真實姓名；
5.2离赫、更新用戶
進入用戶管理界面，點擊用戶列表頁中用戶右側(cè)的"編輯"按鈕可編譯用戶信息塌碌；
5.3渊胸、刪除用戶
進入用戶管理界面，點擊用戶列表頁中用戶右側(cè)的"刪除"按鈕可刪除用戶信息台妆；
六翎猛、版本更新日志
略
七、其他
7.1 項目貢獻
歡迎參與項目貢獻接剩！比如提交PR修復一個bug办成，或者新建 Issue 討論新特性或者變更。
7.2 用戶接入登記
更多接入的公司搂漠，歡迎在 登記地址 登記迂卢，登記僅僅為了產(chǎn)品推廣。
7.3 開源協(xié)議和版權(quán)
產(chǎn)品開源免費桐汤，并且將持續(xù)提供免費的社區(qū)技術(shù)支持而克。個人或企業(yè)內(nèi)部可自由的接入和使用。
- Licensed under the GNU General Public License (GPL) v3.
- Copyright (c) 2015-present, xuxueli.
捐贈
無論金額多少都足夠表達您這份心意怔毛，非常感謝 ：） XXL系列捐贈記錄
