在 API 開發、溝通與協作中,API 文件在邏輯上是標準做法,但在實務上,仍存在以 Word 或 PDF 格式傳遞檔案的問題。因此,提倡使用線上文件來提升團隊之間的溝通效率。建立快速分享#
點擊「New」建立新的快速分享。一個專案支援多個不同的快速分享,可分發給不同的協作者。每位團隊成員都可以看到所有人建立的所有快速分享。標題:此分享的名稱,僅在 Apidog 團隊內可見,用於內部識別,不會顯示在分享的文件中。
環境:選擇線上文件中可用的環境。預設情況下不會選取任何環境。你可以選取多個環境。所選環境會在文件中對讀者可見,並可在使用「Try it out」時用於傳送請求。
如果你在建立文件時選擇 Cloud mock 環境,這等同於為文件讀者啟用一個簡易的沙盒環境。
文件內容:文件有兩個可選元件:Base URL 和請求範例。你可以選擇是否在文件中顯示它們。Base URL:這是在環境中設定的基礎 URL。如果選取,文件中的每個介面都會顯示完整 URL;如果未選取,文件中的 URL 會以「/」開頭。
請求範例:是否顯示呼叫請求的範例程式碼。詳情請參閱請求範例。 允許匯出資料:是否允許讀者以 OAS/Markdown/HTML/Apidog 格式匯出資料。
分享範圍:選擇此分享要包含哪些 API 端點和 Markdown。你可以依目錄選取,或依標籤篩選與排除。
安全性:你可以設定存取此文件是否需要密碼,以及此文件的到期時間。如果未選擇到期時間,則永不過期。
顯示 API 欄位:你可以設定這些欄位是否顯示在文件中。包括:負責人、更新時間、OperationId、原始連結、需要授權。
語言:此處的語言設定會影響文件中的功能性固定文字,例如「Query Params」「Request samples」等,但不會影響 API 文件內容中撰寫的文字。
進階設定:你可以在此設定隱藏「Try it out」按鈕以及隱藏「Powered by Apidog」。
分享整個資料夾#
快速分享支援「分享整個資料夾」。這適用於以下情境:分享連結後,你可能在資料夾中新增或移除了文件,並希望協作者能同步看到這些變更。在「分享範圍」中,當你選擇「手動選取」時,可以看到「分享整個資料夾」。啟用後,協作者將始終看到該資料夾中的所有文件,你無需在新增文件後手動修改分享範圍。請求範例#
你可以在建立分享時選擇是否顯示此模組。
你可以自訂請求範例。方法如下:1.
在 專案設定 - 功能設定 - 端點功能設定 - 端點欄位 中,啟用請求範例欄位。
2.
接著在 端點 - 編輯 中,最後會出現一個請求範例模組。
3.
你可以在此點擊 新增請求範例,加入你所需語言的範例。之後它會顯示在文件中。
分享連結#