寫代碼，哪個程序員都不害怕。

寫文檔，哪個程序員都害怕！

為什么？

還不是因為 API 工具不好使，不便捷，同步麻煩，測試看不懂……

最近調(diào)研了身邊一些開發(fā)團隊，發(fā)現(xiàn)他們列舉的工具中，都出現(xiàn)過同一款工具——Eolink。

今天這次我們深度“盤”一下 Eolink 這款免費 API 協(xié)作平臺，圍繞【智能生成+盤活 API 資產(chǎn)】這一功能上，到底投入了多大的開發(fā)成本，給我們帶來了多少驚喜！

快速體驗：https://www.eolink.com/?utm_source=w5104

本文重點圍繞以下產(chǎn)研需求展開（文末有福利）。

1. 當(dāng) API 代碼更新之后，API 文檔自動刷新；

2. API 協(xié)作工具通過腳本進行自動刷新/同步；

3. 基于 API 文檔智能生成請求代碼和業(yè)務(wù)代碼；

當(dāng)然在正式開始對接 Eolink 前，咱需要先使用 Python Flask 框架在本地構(gòu)建一個微型項目，用于寫接口代碼。

閱讀完這篇，你不但可以編寫公司標(biāo)準(zhǔn)的 Python API 文檔，還順便掌握了 Swagger 與 Eolink 的對接，一舉多得，一文多獲。

一、Eolink 準(zhǔn)備工作，Python 快速搭建 Swagger

我選用的 Web API 框架是 Flask，所以搭建 Swagger 需要用到 Flasgger 模塊，如果你用 FastAPI，可以不用多走這一步，直接使用 FastAPI 原生 API 文檔即可。

使用 Flasgger 得到一個 Swagger UI 具體步驟，不做重點描述，咱們的目標(biāo)是打通 Swagger 和 Eolink，讓 API 研發(fā)資產(chǎn)可以盤活，Swagger 簡易部署流程請參考下述步驟。

首先安裝 flasgger 模塊。

pipinstallflasgger

然后新建 main.py 文件，同時輸入如下代碼（本地 Python 版本為 3.8），代碼有點長，可以跳過閱讀，直接復(fù)制代碼到本地相應(yīng)文件中。

fromflaskimportFlask
fromflasggerimportSwagger

app=Flask(__name__)
swagger=Swagger(app)


@app.route('/eolink_user_add/',methods=['POST'])
defeolink_user(user):
"""
添加用戶
---
tags:
-用戶相關(guān)接口
description:
用戶注冊接口，json格式
parameters:
-name:body
in:body
required:true
schema:
id:添加用戶
required:
-username
-password
properties:
username:
type:string
description:用戶名
password:
type:string
description:密碼
phone:
type:string
description:手機號
wx:
type:string
description:微信

responses:
201:
description:注冊成功


example:{'code':1,'message':注冊成功}
406:
description:注冊失敗
"""
pass


@app.route('/eolink_opts/')
defeolink_opts(t):
"""
Eolink功能描述
---
tags:
-第一個測試接口
description:
傳入大類，返回清單
parameters:
-m_type:number
in:number
type:string
enum:['eolink','eolink1','eolink2','eolink3']
required:false
default:eolink
responses:
200:
description:功能清單
examples:{'eolink':['一站式API生產(chǎn)力工具','超強的API管理','超方便的API測試']}
"""
all_eolink_opts={
'eolink1':['API文檔與研發(fā)管理','API監(jiān)控和異常告警','API快速測試與自動化測試','API微服務(wù)網(wǎng)關(guān)'],
'eolink2':['支持所有主流協(xié)議','代碼自動生成API文檔','API文檔自動生成代碼','API版本管理','API變更通知'],
'eolink3':['支持在線、本地、客戶端進行測試','一鍵進行回歸/冒煙測試','快速創(chuàng)建測試用例','自動生成測試數(shù)據(jù)','豐富詳細(xì)的測試報告']
}
ift=='eolink':
result=all_eolink_opts
else:
result={'eolink':all_eolink_opts.get(t)}

returnresult


@app.route('/',methods=['GET'])
defhello():
return"helloworld!"


if__name__=='__main__':
app.run()

使用 python main.py 運行 Flask 項目，然后訪問 http://127.0.0.1:5000/apidocs/，在瀏覽器得到如下視圖，如果此時你獲得界面與我一直，那么恭喜你，準(zhǔn)備工作已經(jīng)完成，后續(xù)我們需要對上述代碼進行修改，目的是在 Eolink 每次 自動生成 API 文檔 之后，對比差異。

作為一名合格的軟件研發(fā)工程師，在公司團隊協(xié)作開發(fā)的時候，一定要遵守團隊 API 文檔規(guī)范，邊寫代碼，邊寫注釋，邊寫文檔。

在上述界面中，找到 appispec_1.json 超鏈接位置，點擊該鏈接，頁面跳轉(zhuǎn)到 Swagger 生成的 JSON 文件地址，如下所示。

http://127.0.0.1:5000/apispec_1.json

在瀏覽器中直接打開該 URL 地址，得到如下 JSON 格式的數(shù)據(jù)，下圖為部分內(nèi)容展示。

二、Eolink 通過 Swagger 文件，自動生成 API 文檔

在前文拿到 JSON 文件地址后，就可以在 Eolink API 研發(fā)管理平臺讀取該網(wǎng)絡(luò)文件，并自動生成API文檔頁面了，具體操作如下。

進入 API 管理控制臺具體項目中，在左側(cè)菜單欄找到【其它】，然后選擇【API文檔生成】。

可按下述動圖進行操作。

進入到 【自動生成API文檔】功能頁之后，選擇【添加來源】按鈕。

在彈窗中選擇通過 Swagger URL 生成 API 文檔，點擊下一步：

在【添加來源】彈窗輸入 Swagger 生成的 JSON 文件地址，就是剛剛得到的 JSON 文件地址，這里一定要注意，該地址能通過外網(wǎng)訪問（因為 Eolink 服務(wù)器不能調(diào)用我們本地的數(shù)據(jù)），并且為 JSON 格式（剛剛已經(jīng)核對過目標(biāo)數(shù)據(jù)），然后參考下圖進行填寫。

上傳前文獲取的 JSON 文件到臨時服務(wù)器，修改 Swagger.json 文件地址，點擊確定，完成配置。

互聯(lián)網(wǎng)公司項目，文檔一般是支持外網(wǎng)訪問的，這個問題只會在我們學(xué)習(xí)階段碰到。

注意：上圖右側(cè)【完善配置】所有數(shù)據(jù)保持默認(rèn)即可。

點擊確定，完成來源配置，配置頁面自動關(guān)閉，出現(xiàn)如下列表。

點擊同步按鈕，將 Swagger 文件內(nèi)容同步到 Eolink 中。

再次切換到 API 列表頁面，可以看到 API 同步之后的效果。

此時打開 任意API 文檔，可以查看到 API 描述，請求地址，請求參數(shù)，返回參數(shù)等其它信息，到這里 Eolink 已經(jīng)成功進行同步。

如果我們 JSON 文件發(fā)生了任意修改，例如【添加用戶接口】新增加一個 “年齡" 參數(shù)，此時只需要點擊上文提及的同步按鈕，即可更新 Eolink 平臺 API 詳細(xì)數(shù)據(jù)。

這里咱們需要做一個小小的總結(jié)，在公司團隊協(xié)作的場景下，經(jīng)常出現(xiàn)文檔和代碼不同步情況，所以我們引入了 Swagger 模塊，讓小組中的程序員，在編寫代碼的同時，只需要更新自己的代碼和注釋，即可自動生成 API 文檔。

但 Swagger 只是一個用于生成、描述和調(diào)用 RESTful 接口的 Web 服務(wù)，它遠(yuǎn)遠(yuǎn)無法滿足團隊中對于API 的所有訴求，而 Eolink 在軟件研發(fā)整個生命周期中，做了全方位的補充，從而 盤活 API 研發(fā)資產(chǎn)。

除了手動點擊【同步】操作外，我們還可以通過 Open API 實現(xiàn)自動同步。

三、Eolink 通過 Open API 觸發(fā)同步操作

本篇博客中使用的是 Open API V2 版本，在正式編寫代碼前，需要先在工作空間管理后臺獲取調(diào)用密鑰。

密鑰配置

點擊在管理后臺右上角頭像位置的【賬號設(shè)置】，進入工作空間設(shè)置菜單。

切換的頁面中，選擇 【Open API】，進入密鑰配置。

為了數(shù)據(jù)安全，請不要將密鑰泄露。點擊上圖箭頭指向位置，查看密鑰明細(xì)，直接點擊即可復(fù)制。

解析來我們查看一下 通過 Open API 觸發(fā)同步操作的請求說明。

• 請求協(xié)議：HTTPS

• 請求方式：GET

• 請求地址：https://api.eolink.com/v2/api_studio/management/api/auto_scan

• 請求參數(shù)：

  • eo_secret_key：open api 的訪問鑒權(quán)密鑰，前文剛剛復(fù)制的字符串。
  • project_id：當(dāng)前項目的ID，在【自動生成API文檔】頁面已經(jīng)自動填充。
  • space_id：工作空間ID，同樣為 Eolink 自動生成內(nèi)容。

• 請求響應(yīng)

  • 數(shù)據(jù)請求成功，返回 JSON 格式數(shù)據(jù)，{"status":"success"}

有了這些標(biāo)準(zhǔn)之后，我們可以快速通過 Python 編寫一個自動觸發(fā)同步操作的腳本，代碼如下。

importrequests

url="https://api.eolink.com/v2/api_studio/【其余內(nèi)容請在API文檔生成頁面復(fù)制】"

res=requests.get(url)

print(res.text)

在運行代碼前，先對前文的 Python Flask 接口代碼進行一下修改，增加【用戶來源】字段。然后使用上面的 3 行代碼，即可實現(xiàn)自動化同步。上述代碼運行結(jié)果如下所示。

{"type":"api","status":"success"}

閱讀到這里，我們已經(jīng)實現(xiàn)了【通過 Open API 觸發(fā)同步操作】，你可以將代碼部署到云服務(wù)器，并設(shè)置成自動任務(wù)，這樣 Eolink 就可以實時的抓取服務(wù)端 API 文檔，解放你的雙手了。

四、Eolink 基于 IDEA 插件上傳 API

Eolink 除了手動同步和以O(shè)pen API 形式同步文檔以外，還可以通過 IDEA 插件實現(xiàn)快速在研發(fā)工具上操作并上傳API接口文檔，而且比Swagger的方式還快，具體步驟如下所示。

打開 IDEA 插件，再插件市場搜索 Eolink ApiKit。

點擊上圖的 Install 即可安裝。

接下來就需要對該插件進行配置，參照下圖找到 Eolink Settings。

看一下 Eolink Settings 中的相關(guān)參數(shù)配置。

1. Server：這里使用域名+/api 格式，例如這里是 https://space-e87yzg.w.eolink.com/api；

2. SpaceKey：空間Key，復(fù)制上述域名中的Key即可，space-e87yzg；

3. ProjectHashKey：前文 Open API 中用到的 密鑰；

4. Token：你的賬號；

5. StringType：選擇第一項即可。

然后在你的項目源碼空白處，點擊樹表右鍵，選擇 Generate Class Doc，一鍵生成全部 API 注釋文檔。

生成完畢，再次選擇 Upload All Api 即可上傳所有 API 注釋到目標(biāo)服務(wù)器，真正的一鍵生成文檔，一鍵上傳文檔，如果你恰好使用的是 IDEA ，一定要嘗試一下該方式，在 Eolink 的幫助下，寫文檔會變成一件非常輕松的事。

五、基于 Eolink API 文檔智能生成請求代碼和業(yè)務(wù)代碼

前文我們做的所有工作，都是為了讓現(xiàn)有 API 文檔快速生成并同步到 Eolink 中，只有這樣，我們才能體驗 Eolink 這個一站式 API 生產(chǎn)力工具，盤活 API 研發(fā)資產(chǎn)時的強大。

下面將借助剛剛建立的接口，為大家展示 Eolink API 智能生成請求代碼和業(yè)務(wù)代碼這一重點功能，過程中還將為大家介紹 Eolink 的一些小細(xì)節(jié)亮點。

API 文檔同步到 Eolink，一切才剛剛開始！

選擇進入前文同步的任意接口中，可以得到該接口的詳細(xì)描述，更多內(nèi)容可在你的 Eolink 后臺查看，這里僅展示局部。

如果你善于發(fā)現(xiàn)，一定會發(fā)現(xiàn)一個非常不起眼的按鈕 ---【生成預(yù)覽數(shù)據(jù)】，點擊它。這個操作非常適合測試工程師進行數(shù)據(jù)模擬，尤其是當(dāng) API 接口包含大量參數(shù)待填寫時，可以大幅度節(jié)約手寫參數(shù)的消耗時間，而且測試的時候，可以避免使用 abc，aaa，1111，123，這些 “左手亂敲” 的輸入數(shù)據(jù)。

然后我們再看一個強大的功能，生成請求代碼和業(yè)務(wù)代碼，你可以借助 Eolink 生成指定 API 的各語言調(diào)用代碼，操作非常便捷，只需要點擊API文檔詳情頁右上角 “代碼示例” 圖標(biāo)即可。

在彈出的抽屜頁中，可以選擇你需要的代碼示例，這里依據(jù)實戰(zhàn)應(yīng)用場景進行選擇，例如我需要的是 NodeJS 代碼，選擇對應(yīng)語言類型之后，可以得到下圖所示內(nèi)容，下載腳本即可用于請求代碼和業(yè)務(wù)代碼。

最后，我們在補充一個 Eolink 的亮點功能，Eolink 可以直接發(fā)起 API 測試，并且可以在接口前后增加 前置腳本 和 后置腳本，二者的原理是在 API 執(zhí)行前/后 執(zhí)行 Javascript 腳本，從而改變請求參數(shù)或者進行簽名加密等操作。

這部分內(nèi)置變量和內(nèi)置函數(shù)，學(xué)習(xí)和使用時可以參考 Eolink 手冊，點擊閱讀。

使用方式非常簡單，給大家羅列幾個 HTTP 請求相關(guān)的函數(shù)，如下所示。

//輸出信息
eo.info("輸出自定義信息");

//設(shè)置http協(xié)議url，比如/user/login/admin?user_name={{name}}
eo.http.url.set("http://www.baidu.com");

//MD5加密
eo.crypt.md5(data)

上述內(nèi)置函數(shù)，搭配上 Eolink 的 API 自動化測試，可以最大限度的擴展自動化測試需求，真正實現(xiàn)了一鍵發(fā)起測試，一鍵進行 API 回歸測試。

六、總結(jié)

本篇博客，我們從 Eolink 與 Python Flask Swagger 文件打通開始，為大家介紹了兩種 Eolink 同步API 文檔的方法，實戰(zhàn)中還是建議大家在服務(wù)器端部署 Open API 同步腳本，自動化實現(xiàn) Swagger 和 Eolink 同步。

在同步的時候，我們可以進行更加詳細(xì)的配置，擴展如下。

• 數(shù)據(jù)同步方式：增量更新、全量更新、僅添加新API時更新；

• 同步接口唯一標(biāo)識：可選 接口標(biāo)識，接口地址和請求方式，接口名稱；

• 新生成 API 文檔狀態(tài)設(shè)置：已發(fā)布，設(shè)計，待定，開發(fā)，測試等；

• 將發(fā)生變更的 API 文檔狀態(tài)設(shè)置為：已發(fā)布，設(shè)計，待定等；

• 將新生成 API 文檔歸到指定分組：可選API 分組目錄。

Eolink 增加了非常詳細(xì)的同步配置，多方面完善API文檔更新細(xì)節(jié)。

除了API同步外，本文還給大家介紹了 Eolink 的幾個亮點功能，例如自動生成預(yù)覽數(shù)據(jù)，快速生成請求代碼和業(yè)務(wù)代碼，前置后置腳本添加。

審核編輯 ：李倩