寫(xiě)代碼，哪個(gè)程序員都不害怕。

寫(xiě)文檔，哪個(gè)程序員都害怕！

為什么？

還不是因?yàn)?API 工具不好使，不便捷，同步麻煩，測(cè)試看不懂……

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

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

快速體驗(yàn)：https://www.eolink.com/?utm_source=w5104

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

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

2. API 協(xié)作工具通過(guò)腳本進(jìn)行自動(dòng)刷新/同步；

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

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

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

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

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

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

首先安裝 flasgger 模塊。

pipinstallflasgger

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

fromflaskimportFlask
fromflasggerimportSwagger

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


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

responses:
201:
description:注冊(cè)成功


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


@app.route('/eolink_opts/')
defeolink_opts(t):
"""
Eolink功能描述
---
tags:
-第一個(gè)測(cè)試接口
description:
傳入大類(lèi)，返回清單
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)力工具','超強(qiáng)的API管理','超方便的API測(cè)試']}
"""
all_eolink_opts={
'eolink1':['API文檔與研發(fā)管理','API監(jiān)控和異常告警','API快速測(cè)試與自動(dòng)化測(cè)試','API微服務(wù)網(wǎng)關(guān)'],
'eolink2':['支持所有主流協(xié)議','代碼自動(dòng)生成API文檔','API文檔自動(dòng)生成代碼','API版本管理','API變更通知'],
'eolink3':['支持在線(xiàn)、本地、客戶(hù)端進(jìn)行測(cè)試','一鍵進(jìn)行回歸/冒煙測(cè)試','快速創(chuàng)建測(cè)試用例','自動(dòng)生成測(cè)試數(shù)據(jù)','豐富詳細(xì)的測(cè)試報(bào)告']
}
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 運(yùn)行 Flask 項(xiàng)目，然后訪(fǎng)問(wèn) http://127.0.0.1:5000/apidocs/，在瀏覽器得到如下視圖，如果此時(shí)你獲得界面與我一直，那么恭喜你，準(zhǔn)備工作已經(jīng)完成，后續(xù)我們需要對(duì)上述代碼進(jìn)行修改，目的是在 Eolink 每次 自動(dòng)生成 API 文檔 之后，對(duì)比差異。

作為一名合格的軟件研發(fā)工程師，在公司團(tuán)隊(duì)協(xié)作開(kāi)發(fā)的時(shí)候，一定要遵守團(tuán)隊(duì) API 文檔規(guī)范，邊寫(xiě)代碼，邊寫(xiě)注釋?zhuān)厡?xiě)文檔。

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

http://127.0.0.1:5000/apispec_1.json

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

二、Eolink 通過(guò) Swagger 文件，自動(dòng)生成 API 文檔

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

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

可按下述動(dòng)圖進(jìn)行操作。

進(jìn)入到 【自動(dòng)生成API文檔】功能頁(yè)之后，選擇【添加來(lái)源】按鈕。

在彈窗中選擇通過(guò) Swagger URL 生成 API 文檔，點(diǎn)擊下一步：

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

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

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

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

點(diǎn)擊確定，完成來(lái)源配置，配置頁(yè)面自動(dòng)關(guān)閉，出現(xiàn)如下列表。

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

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

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

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

這里咱們需要做一個(gè)小小的總結(jié)，在公司團(tuán)隊(duì)協(xié)作的場(chǎng)景下，經(jīng)常出現(xiàn)文檔和代碼不同步情況，所以我們引入了 Swagger 模塊，讓小組中的程序員，在編寫(xiě)代碼的同時(shí)，只需要更新自己的代碼和注釋?zhuān)纯勺詣?dòng)生成 API 文檔。

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

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

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

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

密鑰配置

點(diǎn)擊在管理后臺(tái)右上角頭像位置的【賬號(hào)設(shè)置】，進(jìn)入工作空間設(shè)置菜單。

切換的頁(yè)面中，選擇 【Open API】，進(jìn)入密鑰配置。

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

解析來(lái)我們查看一下 通過(guò) Open API 觸發(fā)同步操作的請(qǐng)求說(shuō)明。

• 請(qǐng)求協(xié)議：HTTPS

• 請(qǐng)求方式：GET

• 請(qǐng)求地址：https://api.eolink.com/v2/api_studio/management/api/auto_scan

• 請(qǐng)求參數(shù)：

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

• 請(qǐng)求響應(yīng)

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

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

importrequests

url="https://api.eolink.com/v2/api_studio/【其余內(nèi)容請(qǐng)?jiān)贏PI文檔生成頁(yè)面復(fù)制】"

res=requests.get(url)

print(res.text)

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

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

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

四、Eolink 基于 IDEA 插件上傳 API

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

打開(kāi) IDEA 插件，再插件市場(chǎng)搜索 Eolink ApiKit。

點(diǎn)擊上圖的 Install 即可安裝。

接下來(lái)就需要對(duì)該插件進(jìn)行配置，參照下圖找到 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：你的賬號(hào)；

5. StringType：選擇第一項(xiàng)即可。

然后在你的項(xiàng)目源碼空白處，點(diǎn)擊樹(shù)表右鍵，選擇 Generate Class Doc，一鍵生成全部 API 注釋文檔。

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

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

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

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

API 文檔同步到 Eolink，一切才剛剛開(kāi)始！

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

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

然后我們?cè)倏匆粋€(gè)強(qiáng)大的功能，生成請(qǐng)求代碼和業(yè)務(wù)代碼，你可以借助 Eolink 生成指定 API 的各語(yǔ)言調(diào)用代碼，操作非常便捷，只需要點(diǎn)擊API文檔詳情頁(yè)右上角 “代碼示例” 圖標(biāo)即可。

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

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

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

使用方式非常簡(jiǎn)單，給大家羅列幾個(gè) HTTP 請(qǐng)求相關(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 自動(dòng)化測(cè)試，可以最大限度的擴(kuò)展自動(dòng)化測(cè)試需求，真正實(shí)現(xiàn)了一鍵發(fā)起測(cè)試，一鍵進(jìn)行 API 回歸測(cè)試。

六、總結(jié)

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

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

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

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

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

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

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

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

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

審核編輯 ：李倩