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

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

為什么？

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

最近調研了身邊一些開發團隊，發現他們列舉的工具中，都出現過同一款工具——Eolink。

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

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

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

1. 當 API 代碼更新之后，API 文檔自動刷新；

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

3. 基于 API 文檔智能生成請求代碼和業務代碼；

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

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

一、Eolink 準備工作，Python 快速搭建 Swagger

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

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

首先安裝 flasgger 模塊。

pipinstallflasgger

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

fromflaskimportFlask
fromflasggerimportSwagger

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


@app.route('/eolink_user_add/',methods=['POST'])
defeolink_user(user):
"""
添加用戶
---
tags:
-用戶相關接口
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生產力工具','超強的API管理','超方便的API測試']}
"""
all_eolink_opts={
'eolink1':['API文檔與研發管理','API監控和異常告警','API快速測試與自動化測試','API微服務網關'],
'eolink2':['支持所有主流協議','代碼自動生成API文檔','API文檔自動生成代碼','API版本管理','API變更通知'],
'eolink3':['支持在線、本地、客戶端進行測試','一鍵進行回歸/冒煙測試','快速創建測試用例','自動生成測試數據','豐富詳細的測試報告']
}
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/，在瀏覽器得到如下視圖，如果此時你獲得界面與我一直，那么恭喜你，準備工作已經完成，后續我們需要對上述代碼進行修改，目的是在 Eolink 每次 自動生成 API 文檔 之后，對比差異。

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

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

http://127.0.0.1:5000/apispec_1.json

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

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

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

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

可按下述動圖進行操作。

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

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

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

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

互聯網公司項目，文檔一般是支持外網訪問的，這個問題只會在我們學習階段碰到。

注意：上圖右側【完善配置】所有數據保持默認即可。

點擊確定，完成來源配置，配置頁面自動關閉，出現如下列表。

點擊同步按鈕，將 Swagger 文件內容同步到 Eolink 中。

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

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

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

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

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

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

三、Eolink 通過 Open API 觸發同步操作

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

密鑰配置

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

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

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

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

• 請求協議：HTTPS

• 請求方式：GET

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

• 請求參數：

  • eo_secret_key：open api 的訪問鑒權密鑰，前文剛剛復制的字符串。
  • project_id：當前項目的ID，在【自動生成API文檔】頁面已經自動填充。
  • space_id：工作空間ID，同樣為 Eolink 自動生成內容。

• 請求響應

  • 數據請求成功，返回 JSON 格式數據，{"status":"success"}

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

importrequests

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

res=requests.get(url)

print(res.text)

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

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

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

四、Eolink 基于 IDEA 插件上傳 API

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

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

點擊上圖的 Install 即可安裝。

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

看一下 Eolink Settings 中的相關參數配置。

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

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

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

4. Token：你的賬號；

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

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

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

五、基于 Eolink API 文檔智能生成請求代碼和業務代碼

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

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

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

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

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

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

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

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

這部分內置變量和內置函數，學習和使用時可以參考 Eolink 手冊，點擊閱讀。

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

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

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

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

上述內置函數，搭配上 Eolink 的 API 自動化測試，可以最大限度的擴展自動化測試需求，真正實現了一鍵發起測試，一鍵進行 API 回歸測試。

六、總結

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

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

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

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

• 新生成 API 文檔狀態設置：已發布，設計，待定，開發，測試等；

• 將發生變更的 API 文檔狀態設置為：已發布，設計，待定等；

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

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

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

審核編輯 ：李倩