12年經驗的大齡程式設計師，你猜他用什麼寫API文件？
@
目錄- 本篇部落格重點圍繞這些
產研需求展開。 - 一、Eolink 準備工作，Python 快速搭建 Swagger
- 二、Eolink 通過 Swagger 檔案，自動生成 API 文件
- 三、Eolink 通過 Open API 觸發同步操作
- 四、Eolink 基於 IDEA 外掛上傳 API
- 五、基於 Eolink API 文件智慧生成請求程式碼和業務程式碼
- 六、總結
寫程式碼，哪個程式設計師都不害怕。
寫文件，哪個程式設計師都害怕！
為什麼？
還不是因為 API 工具不好使，不便捷，同步麻煩，測試看不懂……
最近橡皮擦調研了身邊一些開發團隊，發現他們列舉的工具中，都出現過同一款工具，Eolink。
今天這次我們深度 “盤” 一下 Eolink 這款免費 API 協作平臺，圍繞【智慧生成+盤活 API 資產】這一功能上，到底投入了多大的開發成本，給我們帶來了多少驚喜！
本篇部落格重點圍繞這些產研需求展開。
- 當 API 程式碼更新之後，API 文件自動重新整理；
- API 協作工具通過指令碼進行自動重新整理/同步；
- 基於 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 模組。
pip install flasgger
然後新建 main.py
from flask import Flask
from flasgger import Swagger
app = Flask(__name__)
swagger = Swagger(app)
@app.route('/eolink_user_add/<user>',methods=['POST'])
def eolink_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/<t>')
def eolink_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': ['支援線上、本地、客戶端進行測試', '一鍵進行迴歸/冒煙測試', '快速建立測試用例', '自動生成測試資料', '豐富詳細的測試報告']
}
if t == 'eolink':
result = all_eolink_opts
else:
result = {'eolink': all_eolink_opts.get(t)}
return result
@app.route('/', methods=['GET'])
def hello():
return "hello world!"
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 編寫一個自動觸發同步操作的指令碼，程式碼如下。
import requests
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 中的相關引數配置。
- Server：這裡使用域名+/api 格式，例如橡皮擦的是 https://space-e87yzg.w.eolink.com/api；
- SpaceKey：空間 Key，複製上述域名中的 Key 即可，space-e87yzg；
- ProjectHashKey：前文 Open API 中用到的 金鑰；
- Token：你的賬號；
- 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 手冊，點選閱讀。
//輸出資訊
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 的幾個亮點功能，例如自動生成預覽資料，快速生成請求程式碼和業務程式碼，前置後置指令碼新增。
最後，希望你能發現更多 Eolink 的使用功能，然後咱們一起在評論區交流一下。
Eolink 一鍵直達：https://www.eolink.com/