作者：Janet Wagner
我們經常被問到 API 規格和 API 文件之間的差異。因此，今天我們想概述 API 文件、API 規格和 API 定義之間的差異和重要性。
什麼是 API 文件？
API 文件本質上是 API 的參考手冊 – 它告訴 API 消費者如何使用 API。API 文件是供人類（通常是開發人員）閱讀和理解的。當確保開發人員擁有良好的 API 體驗時，提供設計良好、全面且易於理解的文件至關重要。良好的開發人員體驗 (DX) 代表 API 成功的機會更大。如果開發人員無法遵循您的 API 文件，他們可能會找到另一個文件更好且更容易整合的 API。良好的文件也有助於減少新 API 消費者加入所需的時間。如果開發人員擁有使用 API 所需的所有資訊，他們就不必向貴公司發送電子郵件、致電您的客戶服務部門或在論壇上發文以獲得幫助。
好的文件包含許多內容，多到無法在此一一列出。但一些使好的 API 文件包括快速入門指南、教學課程和互動式文件，以便開發人員可以嘗試 API 呼叫。有許多工具可用於產生和維護 API 文件。許多這些工具可以從 API 定義檔案自動產生靜態和互動式 API 文件（本文稍後會詳細介紹）。
API 文件應提供每個呼叫、每個參數和每個呼叫的回應範例。它應包括常用語言（例如 Java、JavaScript、PHP 和 Python）的程式碼範例。文件應提供每個 API 請求的說明和錯誤訊息範例。API 文件也必須積極維護並始終保持最新狀態。
什麼是 API 規格？
API 規格是一個經常與 API 定義互換使用的術語。雖然這些術語有許多相似之處，但它們是不同的實體。API 規格提供了對 API 行為方式以及 API 如何與其他 API 連結的廣泛理解。它解釋了 API 的運作方式以及使用 API 時的預期結果。API 規格的一個好例子是 OpenAPI 規格。您可以在 GitHub 上檢視此規格的最新版本 (3.0.1)。
在某些方面，OpenAPI 3.0.1 文件也是 API 文件，但 API 規格解釋了 API 的行為方式以及對 API 的期望。GitHub 上的 OpenAPI 規格文件正是這樣做的。在文件中，有許多 API 物件、值和參數，物件的呼叫方式以及每個物件的作用。我們還看到物件之間的關係以及每個物件的使用方式。
例如，如果您查看請求主體物件部分，您會找到有關此物件的作用、其固定欄位的說明和類型以及請求主體範例的資訊。您將看到請求主體物件應該如何運作以及使用此功能時的期望。API 規格也表示 API 的設計方式和 API 支援的資料類型。
OpenAPI（以前稱為 Swagger 規格）是數種 API 規格語言之一。還有 RAML 和 API Blueprint。應該注意的是，動能正在推動這些 API 規格語言整合為一種 API 規格語言，即 OpenAPI。
什麼是 API 定義？
API 定義與 API 規格類似，因為它提供了對 API 如何組織以及 API 如何運作的理解。但是，API 定義旨在供機器使用，而不是供人類使用 API。API 定義以機器可讀的格式提供有關 API 如何運作、如何與其他 API 連結以及預期結果的資訊。它著重於定義 API 並概述 API 的結構。
API 定義通常用作自動化工具的基準。API 定義可用於自動產生 API 文件、程式碼範例和 SDK。一些從 API 定義檔案產生 API 文件（靜態和互動式）的工具範例包括 SwaggerHub 和 Swagger Inspector。一些可以從 API 定義自動產生範例程式碼和 SDK 的工具範例包括 REST United 和 SwaggerHub。
API 定義也可以匯入模擬伺服器以進行虛擬 API 測試。許多用於模擬伺服器和 API 測試的工具中，允許匯入 API 定義檔案的工具包括 SoapUI 和 SwaggerHub。
API 定義很重要，因為它可以用於支援自動化工具，這些工具可以確保您的 API 成功，例如互動式文件和 SDK。一些開發人員甚至提倡綱要優先的 API 設計，這意味著首先根據其中一種規格語言建立 API 定義，然後編寫 API 的程式碼。
所有相關，但不同
API 文件、API 規格和 API 定義都是相關的，但它們是不同的實體。而且，這些都各有重要的用途。
文件告訴開發人員和其他 API 消費者如何使用 API。畢竟，如果開發人員不知道如何使用您的 API，您的 API 如何成功？
API 規格提供了對 API 功能和預期結果的廣泛理解。規格主要關於 API 的設計或您的設計理念。API 設計和功能是在選擇將 API 與應用程式整合時的關鍵因素。
最後，API 定義是關於 API 的機器使用，並提供機器可讀的格式，供自動化工具（例如自動 API 文件和 SDK 產生器）使用。
API 文件、API 規格和 API 定義都是 API 成功的關鍵。
感謝您的閱讀！正在尋找更多 API 資源嗎？訂閱 Swagger 電子報。每月接收包含我們最佳 API 文章、培訓、教學及更多內容的電子郵件。訂閱