API 規格與 OAS

正如您在之前的文章中所學到的——涵蓋了方法、路徑、參數、請求 Body 和回應——下一步是了解 API 規格 (spec) 的概念以及最廣泛使用的標準之一：OpenAPI 規格 (OAS)。

1. 什麼是 API 規格？

API 規格是一份文件（或機器可讀檔案），準確描述 API 如何運作。它充當 API 提供者與消費者之間的契約，解釋：

存在哪些端點（例如 /pets/{id}）

您可以使用什麼方法 (GET, POST 等)

需要什麼參數或請求 Body

您將收到什麼回應結構 (資料結構)

需要什麼 Auth

換句話說：當您看到規格時，您就知道如何正確呼叫 API 並安全地解釋回應。

2. 為什麼使用 API 規格？

它標準化了 API 的描述方式，以便每個開發者都能快速理解。 (openapis.org)

它啟用了工具和自動化：您可以從規格生成互動式文件、客戶端函式庫、Mock 伺服器和測試。 (swagger.io)

它改善了協作：前端、後端、QA 團隊都根據同一份「契約」工作。 (apideck.com)

3. 規格生命週期

API 規格不是靜態的——它隨著 API 一起演進。其生命週期通常包括：

設計階段

規格在 API 實作之前編寫。

作為開發者、前端團隊和 QA 的藍圖。

您可以在 Apidog 中直觀地設計 API 規格。

實作階段

後端開發者根據規格實作端點。

如果發生變更，規格可能會更新。

在 Apidog 中，開發者可以直接從 API 規格生成伺服器 stubs。

測試與文件階段

QA 團隊和工具使用規格來生成測試和 Mock 伺服器。

開發者和消費者可以使用像 Apidog 這樣的工具探索 API。

維護階段

任何 API 變更（新端點、更新的請求/回應）都會觸發規格的更新。

在 Apidog 中，規格仍然是人類和機器的單一事實來源。

了解生命週期有助於您信任規格，並知道它應該與實際 API 行為相符。

4. OpenAPI 規格 (OAS)

OpenAPI 規格 (OAS) 是編寫機器可讀 API 規格的廣泛採用的標準。

該專案最初於 2010 年以 "Swagger" 之名推出，旨在簡化 API 文件和設計。2016 年，Swagger 規格更名為 OpenAPI 規格並捐贈給 Linux 基金會。它現在由 OpenAPI Initiative 管理，其中包括 Google、Microsoft 和 IBM 等行業領導者。

為什麼使用 OAS？

標準化：OAS 提供了一種統一且一致的格式（JSON 或 YAML）來記錄 API。這使得開發者、建立者和消費者更容易跨不同平台和程式語言理解、整合和構建 API。

自動化：像 Apidog 這樣的工具可以直接從 OAS 檔案生成互動式且人性化的文件。其他工具使用 OAS 生成程式碼 stubs、伺服器框架和 API 測試。

改善協作：清晰定義的 OAS 文件充當 API 契約，簡化團隊成員之間的溝通與對齊——包括後端、前端、QA 和產品利害關係人。

更好的測試：由於 OAS 檔案定義了 API 的預期行為和結構，自動化測試工具可以在部署之前驗證正確的實作。

一個最小的 OAS 文件包含以下部分：

解釋：

openapi — 規格版本

info — API Metadata (標題, 描述, 版本)

servers — 請求的基本 URL

paths — 端點和方法

components — 可重複使用的資料結構、參數和物件

4. 如何使用 API 規格

大多數 API 提供可下載的規格檔案（JSON 或 YAML 格式）。這些檔案通常在文件中有連結。

範例： 在 Pet Store API 中，文件頁面底部有一個 「Export」 按鈕。

取得 API 規格檔案後，您可以點擊 Apidog 主介面上的「+」按鈕並選擇「Import」。

選擇「OpenAPI/Swagger」類型，然後拖放您剛下載的規格檔案。點擊「Finish」，您將能夠在 Apidog 中視覺化地與 API 規格互動，以進行 API 的除錯、測試和 Mock。

5. 重點摘要

API 規格是您正確理解和使用 API 的地圖。OpenAPI 規格提供了一種標準化的、機器可讀的格式，啟用了：

互動式文件

自動化測試

客戶端程式碼生成

團隊之間可靠的溝通

透過了解 API 規格的目的、生命週期和結構，您可以自信地探索任何 API、建構請求、解釋回應，並利用工具更高效地工作。

您現在已經了解了將一切維繫在一起的藍圖——API 規格。這結束了我們對 API 基礎建模組的深入探討。

讓我們在 章節總結 中回顧我們在本章中學到的所有內容。

1. 什麼是 API 規格？#

2. 為什麼使用 API 規格？#

3. 規格生命週期#

4. OpenAPI 規格 (OAS)#

為什麼使用 OAS？#

4. 如何使用 API 規格#