API管理平臺XXL-API

《API管理平臺XXL-API》

1、簡介

1.1 概述

XXL-API是一個簡潔易用API管理平臺，提供API的"管理"、"文檔"、"Mock"和"測試"等功能。現已開放源代碼，開箱即用。

1.2 特性

• 一、極致簡單：交互簡潔，一分鐘上手；
• 二、項目隔離：API以項目爲維度進行拆分隔離；
• 三、分組管理：單個項目內的API支持自定義分組進行管理；
• 四、標記星級：支持標註API星級，標記後優先展現；
• 五、API管理：建立、更新和刪除API；
• 六、API屬性完善：支持設置豐富的API屬性如：API狀態、請求方法、請求URL、請求頭部、請求參數、響應結果、響應結果格式、響應結果參數、API備註等等；
• 七、markdown：支持爲API添加markdown格式的備註信息；
• 八、Mock：支持爲API定義Mock數據並制定數據響應格式，從而快速提供Mock接口，加快開發進度；
• 九、在線測試：支持在線對API進行測試並保存測試數據，提供接口測試效率；

1.3 下載

源碼地址 (將會在兩個git倉庫同步發佈最新代碼)

• github地址
• git.osc地址

博客地址 (將會在兩個博客同步更新文檔)

• oschina地址
• cnblogs地址

技術交流羣 (僅做技術交流)

• 羣2：438249535
• 羣1：367260654 （羣1已滿，請加羣2）

1.4 環境

• Servlet/JSP Spec：3.0/2.2
• JDK：1.7+
• Tomcat：7+/Jetty8+
• Mysql：5.6+
• Maven：3+

2、快速部署

2.1 初始化「調度數據庫」

請下載項目源碼並解壓，獲取 "初始化SQL腳本"，腳本位置：

/xxl-api/db/xxl-api-mysql.sql

2.2 編譯源碼

解壓源碼,按照maven格式將源碼導入IDE, 使用maven進行編譯便可，源碼結構以下圖所示：

2.3 配置JDBC鏈接

在如下項目文件中設置應用的JDBC鏈接；

/xxl-api/xxl-api-admin/src/main/resources/xxl-api.properties

2.4 部署

將應用"xxl-api-admin"部署在容器如Tomcat下以後，啓動後訪問便可進入如下界面：

3、項目管理

系統中API以項目爲單位進行管理，所以首先須要管理項目；項目管理界面以下圖所示；

3.1 新建項目

進入項目管理界面，點擊右側"+新增項目"按鈕可新建項目，以下圖所示：

項目屬性說明：

項目名稱：項目的名稱；
項目描述：項目的描述信息；
訪問權限："公開"權限，表示全部人可操做；"私有"權限，表示只有管理員或者項目成員能夠操做（功能自測中，即將推送）；
跟地址-線上環境：項目線上環境跟地址，項目中的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屬性說明：

基礎信息：
    接口分組：接口所屬的分組；
    接口狀態：接口的狀態，在接口列表中，啓用狀態接口用綠色圓圈標識，維護狀態接口用黃色圓圈標識，廢棄狀態接口用灰色圓圈標識；
    請求方法：請求方法，如POST、GET等；
    接口URL：接口請求的URL地址，注意此處爲相對地址，跟地址從所屬項目的跟地址屬性上獲取；
    接口名稱：接口的名稱；
請求頭部：同一接口支持設置多個請求頭部；
    頭部標籤：請求頭部的類型，如Accept-Encoding；
    頭部內容：請求頭部的數據，如Accept-Encoding頭部標籤的頭部內容UTF-8；
請求參數：同一接口支持設置多個請求參數；
    是否必填：該參數是否必填；
    參數類型：該參數的數據類型，如STRING；
    參數名稱：參數的名稱；
    參數說明：參數的說明；
響應結果：分別支持設置 "成功響應結果" 和 "失敗響應結果"，做爲接口響應數據的參考；
    響應數據類型(MIME)：響應結果類型，如JSON、XML等；
    響應結果數據：響應結果的數據，如響應結果類型爲JSON時可設置響應結果數據爲一段JSON數據；
響應結果參數：對接口"響應結果"中參數的補充說明，如響應結果類型爲JSON時，可在此處一一列出JSON各個字段的參數信息；
    是否非空：該參數是否可能爲空；
    參數類型：該參數的數據類型，如STRING；
    參數名稱：參數的名稱；
    參數說明：參數的說明；
接口備註：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、用戶管理

5.一、新增用戶

進入用戶管理界面，點擊右上角"+新增用戶"按鈕，可添加用戶信息；

用戶屬性說明：

登陸帳號：用戶的登陸帳號；
登陸密碼：用戶的登陸密碼；
用戶類型：
    普通用戶：只容許操做公開項目，或者本身擁有項目權限的私有項目；
    超級管理員：擁有全部項目的操做權限；
真實姓名：用戶的真實姓名；

5.二、更新用戶

進入用戶管理界面，點擊用戶列表頁中用戶右側的"編輯"按鈕可編譯用戶信息；

5.三、刪除用戶

進入用戶管理界面，點擊用戶列表頁中用戶右側的"刪除"按鈕可刪除用戶信息；

6、版本更新日誌

6.1 版本 V1.0.0，新特性

• 一、極致簡單：交互簡潔，一分鐘上手；
• 二、項目隔離：API以項目爲維度進行拆分隔離；
• 三、分組管理：單個項目內的API支持自定義分組進行管理；
• 四、標記星級：支持標註API星級，標記後優先展現；
• 五、API管理：建立、更新和刪除API；
• 六、API屬性完善：支持設置豐富的API屬性如：API狀態、請求方法、請求URL、請求頭部、請求參數、響應結果、響應結果格式、響應結果參數、API備註等等；
• 七、markdown：支持爲API添加markdown格式的備註信息；
• 八、Mock：支持爲API定義Mock數據並制定數據響應格式，從而快速提供Mock接口，加快開發進度；
• 九、在線測試：支持在線對API進行測試並保存測試數據，提供接口測試效率；

6.12 版本 V1.0.1 特性（Coding）

• 一、項目權限：支持對項目設置權限，擁有權限才容許操做項目中API；

TODO LIST

• 一、項目權限：支持對項目設置權限，擁有權限才容許操做項目中API；
• 二、API歷史版本：支持對API修改歷史版本進行對比，版本回溯等操做；

7、其餘

7.1 報告問題

XXL-API託管在Github上，若有問題可在 ISSUES 上提問，也能夠加入上文技術交流羣；

7.2 接入登記（登記僅爲了推廣，產品開源免費）

更多接入公司，歡迎在github 登記

---

支持的話能夠掃一掃，支持 XXL系列 的建設。