API 文件：概覽

到目前為止，您已經學會如何設計、Mock 和測試您的 API。您已經使用 Pet Store User 模組建立了堅實的基礎。現在，是時候透過記錄和發布它來為您的消費者釋放該工作的全部價值了。

文件是您 API 的使用者介面。無論您的 API 多麼強大或高效，如果開發者無法理解如何使用它，它就不會被採用。Apidog 透過直接從您的 API 設計自動生成精美、互動式的文件來簡化此過程。

在本章中，我們將採用我們之前設計的 User 模組，並將其轉變為專業的開發者入口網站 (Developer Portal)。

為什麼 API 文件很重要？

文件連接著您編寫的程式碼和使用它的開發者。

1. 開發者體驗 (DX)

良好的文件減少了摩擦。它允許開發者：

快速了解您的 API 做什麼。

無需猜測即可找到他們需要的端點。

複製貼上可運作的程式碼範例。

2. 單一事實來源 (Single Source of Truth)

使用 Apidog，您的文件與您的 API 設計連結。

您不需要在通用的文書處理器中分開編寫文件。

當您更新端點設計時，文件會自動更新。

這防止了「過時文件」的常見問題。

3. 降低支援成本

清晰、互動式的文件在問題被提出之前就回答了常見問題。當開發者可以直接在瀏覽器中「Try it out」時，他們可以自行排除問題。

您將學到什麼

在本章中，您將掌握 Apidog 中的「Docs-as-Code」工作流程：

發布您的第一個文件網站 — 了解內部團隊的「快速分享」與供公眾使用的「發布文件」之間的區別。您將發布您的 User 模組。

自訂文件外觀 — 讓您的文件看起來很專業。自訂導覽、主題和品牌以符合您組織的風格。

給消費者的互動功能 — 探索「Try it out」控制台、Mock 伺服器整合以及使用戶端程式碼生成功能，這些功能使您的文件「活起來」。

進階發布設定 — 透過自訂網域、SEO 最佳化和進階樣式來控制您的文件呈現。

管理 API 版本 — 學習如何透過管理多個版本的文件網站來處理 API 演進。

先決條件

在開始本章之前，您應該：

擁有一個設計了一些 API 端點的專案（我們將使用 設計 APIs 章節中的 Pet Store User 模組）。

對什麼是「公開 API」有基本的了解。

「Doc-as-Code」理念

Apidog 遵循一種理念，即文件不是事後的想法——它是良好設計的直接副產品。

設計您的 API（路徑、資料結構、回應）。

註釋描述和範例（就像我們在 設計 APIs 章節中所做的那樣）。

一鍵發布。

您已經完成了設計 User 模組的艱苦工作。現在，看看將它呈現給世界是多麼輕鬆。

準備好發布了嗎？讓我們從 發布您的第一個文件網站 開始。

為什麼 API 文件很重要？#

1. 開發者體驗 (DX)#

2. 單一事實來源 (Single Source of Truth)#

3. 降低支援成本#

您將學到什麼#

先決條件#