管理 API 版本

API 會變更。您可能會新增一個新參數、棄用一個舊端點，或完全重組回應格式。您如何在不破壞現有使用者文件的情況下處理此問題？

Apidog 的 Versioning（版本控制）功能允許您同時維護多個版本的文件（例如 v1.0, v2.0）。

何時進行版本控制？

Breaking Changes (破壞性變更)：如果您移除欄位或更改 Auth，您必須進行版本控制。

主要功能：v2.0 的大修通常需要一套全新的文件。

次要更新：對於小的非破壞性變更（新增欄位），您通常只需更新當前版本，而不是建立新版本。

在 Apidog 中，一個版本本質上是您 API 資源的快照。

前往 Project Settings > Versions。

建立一個新版本（例如 v2.0）。

您可以選擇複製 v1.0 的所有端點作為起點。

現在，您有兩個隔離的工作區。v2.0 中的變更不會影響 v1.0 的設計。

一旦您設計了多個版本，您需要將它們暴露給使用者。

前往 Share Docs > Publish > Release。

您將看到版本列表。

Add 您想要顯示的版本（v1.0, v2.0）。

為每個版本設定 Slug（例如 /v1, /v2）。

安排順序。最上面的一個通常是 Default（預設）。

在您發布的文件網站上，一個 Version Selector（版本選擇器）下拉選單將出現在左上角（專案標題旁）。

使用者可以在 v1.0 和 v2.0 之間切換。

URL 將相應變更（例如 docs.example.com/v1/...）。

版本控制策略：在引入破壞性變更時對文件進行版本控制，以確保對現有使用者的向後相容性。

快照版本：Apidog 中的版本是您 API 資源的快照，允許您在設計 v2.0 時維護 v1.0。

發布管理：同時發布多個版本，讓使用者透過下拉選擇器在它們之間切換。

使用者體驗：清晰的版本控制標誌著成熟與穩定，讓開發者有信心在您的平台上進行構建。

這確保了即使您在創新，也永遠不會拋棄您的舊有使用者。

您已經掌握了記錄 API 的藝術。現在，讓我們用 章節總結 來總結本章。