Spec-first 模式 (Beta)

Spec-first 模式適用於希望將 API 規格檔案作為單一事實來源的團隊。在此模式中，你可以直接在 Apidog 中設計與維護 OpenAPI 或 Swagger 檔案，在編輯時預覽產生的 API 文件，並讓檔案與 Git 保持同步。

當你的團隊已經使用 YAML 或 JSON 規格檔案、透過 Git 審查 API 變更，或希望 API 設計自然融入程式碼儲存庫工作流程時，請使用 Spec-first 模式。

Spec-first 模式的運作方式

在一般的 Apidog 專案中，API 通常是透過視覺化表單建立與編輯。在 Spec-first 專案中，主要工作區是以檔案為基礎。

你會使用如下檔案：

openapi.yaml

openapi.json

Swagger 2.0 檔案

Markdown 檔案及其他支援專案檔案

Apidog 會解析規格檔案，並將其轉換為可瀏覽的 API 結構。你可以編輯原始檔案、使用支援的視覺化表單、驗證規格、預覽產生的文件，並將變更推送回 Git。

建立 Spec-first 專案

點選 + New Project。

在專案類型選擇器中，選擇 Spec-first Mode。

連接 Git 提供者，例如 GitHub、GitLab、Azure DevOps 或 Bitbucket。

選擇組織或工作區，然後選擇既有儲存庫，或在選項可用時建立新的儲存庫。

選擇 Apidog 應同步的主分支。

選擇是否安裝 webhook。

安裝 webhook 可讓 Git 儲存庫中的推送觸發自動同步。這通常需要該儲存庫的管理員權限。如果你沒有管理員權限，可以略過 webhook 安裝並手動同步。

輸入專案名稱、設定成員權限，然後點選 Create。

建立後，Apidog 會執行第一次同步。如果儲存庫的預設分支不是 main，Apidog 會使用儲存庫分支名稱作為專案主分支。

Spec-first 專案不包含範例專案資料。API 內容來自你的規格檔案。

Specs 工作區

Spec-first 專案在左側邊欄中包含 Specs 工作區。這是管理規格檔案與 Git 同步的主要位置。

工作區包含三個主要區域：

檔案總管：瀏覽並管理來自同步儲存庫的檔案與資料夾。

API 結構樹：瀏覽已解析的 OpenAPI 內容，例如概觀、端點、結構描述與定義。

編輯器：以程式碼檢視編輯檔案；或針對支援的 OpenAPI 節點，以表單檢視編輯。

當你在結構樹中選擇端點、結構描述或其他支援的節點時，Apidog 會開啟來源檔案中的相關部分。這讓你可以在檔案層級檢視與 API 層級檢視之間切換，而不必離開 Specs 工作區。

編輯規格檔案

編輯器支援不同的檔案類型與編輯模式。

程式碼檢視

使用 Code 檢視直接編輯 YAML、JSON、Markdown 及其他文字檔案。這是在 Spec-first 模式中工作的預設方式。

表單檢視

針對支援的 OpenAPI 節點，Apidog 也提供 Form 檢視。這可讓你透過結構化控制項編輯常見 API 欄位，同時仍將底層規格檔案作為單一事實來源。

表單檢視適用於支援的節點，例如：

API 概觀

端點

結構描述

定義

如果選取的檔案或節點無法在表單檢視中編輯，Apidog 會讓你維持在程式碼檢視。

編輯時驗證與預覽

Spec-first 模式在編輯器標頭中包含驗證與預覽工具。

驗證

Validation 面板會顯示目前規格中偵測到的問題，包括警告與錯誤。驗證徽章會顯示偵測到的問題總數。

使用此面板在提交變更前找出語法問題、缺少必要欄位以及規則違反。

預覽

Preview 面板會顯示所選規格節點在產生的 API 文件中會如何呈現。

預覽適用於：

API 概觀

端點

結構描述

定義

對於端點，Preview 包含：

Docs：產生的端點文件。

Try it out：用於根據所選端點定義傳送請求的請求面板。

對於結構描述、定義與概觀節點，Preview 會顯示產生的文件檢視。

Validation 與 Preview 使用相同的側邊面板。開啟其中一個會關閉另一個。

從 Git 同步變更

當其他團隊成員將變更推送到已連接的儲存庫時，你可以將最新檔案拉取到 Apidog。

開啟 Specs 工作區。

在 Specs 側邊欄中點選目前分支名稱。

點選 Git Pull。

如果已安裝 webhook 同步，Apidog 也可以從 Git 提供者接收推送事件並自動觸發同步。

提交並推送變更到 Git

在 Apidog 中編輯檔案後，將你的變更推送回已連接的儲存庫。

在 Specs 工作區中編輯一個或多個檔案。

點選 Changes 以檢視已修改、新增、重新命名與刪除的檔案。

點選 Commit & Push。

在 Push to Git repo 彈窗中，選擇你想包含的檔案。

輸入提交訊息。

點選 Push。

如果你不想保留本機編輯，請在推送前使用 Discard all changes。

管理分支

Spec-first 模式支援以分支為基礎的協作。Apidog 會將同步的 Git 分支對應到專案分支，讓你可以在不同版本的規格之間切換。

切換分支

在 Specs 側邊欄中點選分支名稱，並從下拉選單選擇另一個分支。

追蹤既有 Git 分支

如果某個分支存在於 Git 中但尚未匯入 Apidog，請點選 Import New Branch，選擇該分支並匯入。Apidog 隨後會開始追蹤並同步該分支。

建立分支

開啟 Project Settings > Git & Branches，然後點選 New Branch，從既有專案分支建立分支。

重新同步分支

如果分支同步失敗或檔案看起來不是最新狀態，請在 Project Settings > Git & Branches 中使用 Re-sync。這會重設該分支的同步狀態並再次匯入檔案。

檢視同步記錄

如果同步失敗，請開啟分支操作並選擇 View Logs，以檢查同步詳細資料。

停止追蹤或刪除分支

刪除已追蹤的分支會將其從 Apidog 的同步設定中移除。對於非主分支，也可以移除專案分支記錄。

Webhook 同步與權限

Webhook 同步是選用功能，但建議希望 Apidog 隨儲存庫推送保持最新狀態的團隊使用。

啟用 webhook 同步時：

Apidog 會在已連接的 Git 提供者上註冊 webhook。

只會處理支援的推送事件。

Apidog 會在同步前驗證 webhook 簽章或權杖。

權限需求：

安裝 webhook 通常需要儲存庫管理員權限。

推送變更需要寫入權限。

如果略過 webhook 安裝，仍可使用手動同步。

如果你在建立專案時略過 webhook 安裝，可以稍後從 Project Settings > Git & Branches 安裝。

以儲存空間為後端的 Spec-first 專案

某些 Spec-first 專案可能會使用 Apidog 的內部儲存空間，而不是外部 Git 儲存庫。

這些專案仍會使用 Specs 工作區、以檔案為基礎的編輯、驗證、預覽與分支管理。

UI 標籤略有不同：

Git Pull 會顯示為 Sync。

Commit & Push 會顯示為 Save。

Git 提供者資訊與外部 webhook 設定會隱藏。

注意事項與限制

Spec-first 模式目前處於 beta 階段。

Specs 工作區只會出現在 Spec-first 專案中。

Spec-first 專案不會建立範例 API 資料。

規格檔案是單一事實來源。變更應透過 Specs 工作區進行，或透過 Git 同步。

如果你沒有足夠的儲存庫權限，webhook 安裝可能會失敗。只要你有寫入權限，仍可使用手動同步。

Spec-first 模式 (Beta)

Spec-first 模式的運作方式#

建立 Spec-first 專案#

Specs 工作區#

編輯規格檔案#

程式碼檢視#

表單檢視#

編輯時驗證與預覽#

驗證#

預覽#

從 Git 同步變更#

提交並推送變更到 Git#

管理分支#

切換分支#

追蹤既有 Git 分支#

建立分支#

重新同步分支#

檢視同步記錄#

停止追蹤或刪除分支#

Webhook 同步與權限#

以儲存空間為後端的 Spec-first 專案#

注意事項與限制#