Skip to main content
Version: 2.8.1

API文件

API文件可以對服務新增 API Swagger 文件，並且擁有對此文件做版本管理及API測試的功能。

儲存為新版本#

點擊左上角 儲存為新版本 ，即可將目前的 swagger 文件儲存成一個新版本，可以自定義目前版本的 Ｍemo 送出。

API文件

版本管理#

點擊左上角 版本管理 後，可進入版本管理頁面。在此可看到所有版本清單以及每個版本對應的 swagger 文件資訊。

如想查看某個版本的資訊，可點擊對應的 版號 ，就會顯示該版號的詳細資訊，如： swagger 文件內容、版本之間的差異、自動化測試的報告。

API文件1

公開並發布 swagger 文件#

可以設定該版本是否要公開給其餘外部使用者查看，外部使用者可在開發者介面上看到已公開的文件。

API文件2

將文件設為公開#

將文件設為公開後，有訂閱此服務的使用者，且有設定信箱的使用者們，會收到一封主旨為：[GOC API Gateway] Service Subscription 的通知信，提醒使用者可以前往開發者介面查看。

開發者介面網址可以使用 API Gateway Proxy Url 加上 /openDocs 去進行存取，假設 Proxy Url 為 http://10.15.111.1:31215，則可以在瀏覽器網址列上輸入 http://10.15.111.1:31215/openDocs，便會自行跳轉至開發者介面。若不知道 Proxy Url 如何取得，可以參考 常見問題。

管理員可分享開發者介面網址給外部使用者，外部使用者就可以查看目前已公開的 swagger 文件，來進行後續的 API 開發串接（如下圖）。

開發者介面

設定 Release Note#

可以點選「 Release Note 」按鈕，設定該次文件發布的 Release Note 內容。

使用者就可以從開發者介面上看到新版 API 的版本異動說明。

API 測試#

可以對目前最新的 swagger 文件版本進行自動化測試，可點擊右側的 API 測試 按鈕 ，填入主機位置、帳號及密碼即可做 API 測試。

  • 主機位置：要測試的 API Endpoint，實際上可以搭配 swagger 文件定義的 API 路徑所呼叫到的服務 URL。
  • 帳號：呼叫 swagger 文件定義的 API 時需要帶入的 Basic Auth 的帳號，若本身 API 設定不需傳入帳密，則此欄位可隨意填寫(必填)。
  • 密碼：呼叫 swagger 文件定義的 API 時需要帶入的 Basic Auth 的密碼，若本身 API 設定不需傳入帳密，則此欄位可隨意填寫(必填)。

API 測試會依照目前設定之主機位置、帳號及密碼來對 swagger 文件定義的每支 API 發出請求，自動測試各個 API 是否能正常被存取呼叫。

API文件5

swagger 文件內容#

可看到此版本完整的 swagger 文件內容。

API文件3

對比#

可看到選擇之版號與前一版之差異。

API文件4

測試報告#

若有執行過 API 測試，則測試結果會顯示在 測試報告 頁籤中，若進行多次的自動化測試，測試報告只會保留最新一次的自動化測試結果。

API文件6