創世資訊 GENESiS

良好的使用者體驗對於使用任何產品都至關重要，對於API也是如此。使用於API的介面越好，實現您的業務和技術目標的機會就越高。自從行動和雲端運算的出現以來，API已經成為主流，越來越多的公司和組織了解建立API的業務價值。隨著許多網路服務的出現，明確的API文件對於採用這些服務變得非常重要。

API文件是成功使用和整合API所需的資訊。這可以是技術文件、程式碼範例和示範，以更好地理解如何使用API。對企業和組織來說，希望能有更多人和客戶來使用自己的API，簡潔和清晰的文件已經不再是個可有可無的選項，而是絕對必要的。

當然，如果您不想花時間學 OpenAPI 只要快速上手，可以參考新版 SwaggerHub 表單編輯器。

文件化為什麼重要

ProgrammableWeb 的一項調查發現，API 使用者將完整且準確的文件視為其 API 決策的最大因素，甚至超過了價格和 API 效能。

良好的文件可以加速開發和使用，並減少客服回應和技術支援所花費的金錢和時間。文件是整體使用者體驗的一部分，也是增加 API 成長和使用的最大因素之一。

API文件的挑戰

與許多其他產品一樣，API 在開發和發布週期中往往會快速發展。為您的開發團隊和最終使用者維護和更新此文件，以便他們有效地使用 API，成為一個困難的過程。如果您使用靜態文件（如 .pdf）分享給最終使用者，這個問題變更為顯著。第二個問題是如何促進多個 Web Service 之間的互動。應用程式由多個服務組成，而這些服務不斷地相互溝通和互動。

隨著 RESTful 服務數量的增長，用於實現它們的程式語言也在不斷增加，這使得它們之間的通訊變得更加困難。API 文件可以被認為是使用 API 的接口，因此需要促進這些不同 Web Service 之間的互動。常規 API 接口，無論是純文字的文件還是 Javadoc 等其他格式，都不允許它們相互通訊。這些挑戰以及其他 API 痛點導致了 Swagger 規範的建立。

在下一節中，我們將仔細研究 OpenAPI 規範—以前稱為 Swagger 規範—如何協助您解決文件化的挑戰。

為什麼要使用 OpenAPI 來取得 API 文件

在 Swagger 團隊加入 SmartBear 並將該規範於 2015 年捐贈給 OpenAPI Initiative 後，Swagger 規範更名為 OpenAPI 規範 (OAS)，現已成為定義 RESTful API 的實務標準。

註：我們將在整個資源中使用術語 OpenAPI 和 OAS。這是為了引用規範。

OAS 定義了 API 的契約，允許所有 API 的利害關係人（無論是您的開發團隊還是最終使用者）了解 API 的用途並與其進行各種資源類別的互動，而無需將其整合到自己的應用程式中。該契約與程式語言無關，而且是人類可以閱讀的，方便機器和人員共同解析和理解 API 應該做什麼。

OAS 契約描述了 API 的功能、 Request 參數和 Response 對象，這一切都和程式碼是怎麼寫的無關。使用 OAS 定義的 Web Service 可以相互溝通且無關使用哪種語言建立，因為 OAS 本身就是和語言無關，並且是機器也可讀的。

OAS 如何協助撰寫文件？

Swagger 首次獲得採用的最大原因之一是它能夠幫助簡化 RESTful API 的文件。使用 Swagger UI 等工具（無論是開源工具還是 SwaggerHub 內的工具），您可以將 OAS 契約轉換為互動式 API 控制台，使用者可以使用該控制台與 API 互動並快速了解 API 的行為方式。

為 API 產生文件只是使用 OpenAPI 定義 API 的優勢之一。其他好處包括：

• 幫助內部團隊成員理解 API 並就其屬性達成一致： API 定義允許 Swagger UI 等文件工具視覺化 API。您可以將我們內部的所有API視覺化，以便開發者可以快速、輕鬆地使用上下游服務。SwaggerHub 等基於團隊的工具允許在 API 文件上進行協作並託管它們以供內部使用。
• 幫助外部人員了解 API 及其功能：同樣，Swagger UI 是一個常用的文件視覺化工具。不僅用於內部消費，也用於外部採用。SwaggerUI 具有內建的互動性，因此外部用戶可以嘗試 API 的每個資源並在其程式碼庫中使用之前熟悉它。使用 SwaggerHub Portal，組織還可以為其外部用戶提供受控存取。
• 為您的 API 建立測試：您的 OAS 定義提供了一個契約，該契約描述了當有人呼叫您的 API 時成功 Response 的樣子。該契約還可以重新用於產生測試案例，這可以大大減少測試 API 所需的設定團隊的數量。
• 產生實作程式碼和 SDK：除了產生文件之外，OpenAPI 定義還可以透過為 API 建立實作程式碼和 SDK 來加速開發。API 定義檔可以匯入到許多不同的工具中，例如 Swagger Codegen 和 SwaggerHub，以使用許多不同的語言（例如 Java、Scala 和 Ruby）來建立這些存根程式碼。

現在我們已經介紹了為什麼您的團隊應該在 API 開發工作流程中採用 OAS 和 Swagger 工具，下一個問題是您如何真正開始？在下一節中，我們將仔細研究開始使用 OAS 的不同方法。

OpenAPI 的方法

在建立 OAS 定義時，出現了兩個重要的學派：API 開發的「設計優先」和「程式碼優先」方法。

設計優先方法主張在編寫任何程式碼之前先設計 API 的契約。這是一種相對較新的方法，但很快就流行起來，尤其是在使用 OpenAPI 的情況下。在設計優先的方法中，API 契約充當中心草案，使所有團隊成員就 API 的目標以及 API 資源的公開方式保持一致。

在編寫任何程式碼之前發現設計中的問題比在實施已經就位之後發現問題更加有效和簡化。

如果您的團隊準備好過渡到設計優先方法，您首先需要熟悉編寫 API 定義。以下是一些可幫助您開始此過程的資源：

• 教學課程—學習新的 OpenAPI 規格：您可以在 Swagger.io 上找到 OpenAPI 3.0 和 Swagger 2.0 規範的文件。
• 如何使用最新的 OpenAPI 規範設計和記錄 API [網路研討會錄影]：本培訓提供了在 SwaggerHub 中使用 OpenAPI 3.0 定義新 API 的現場演示。
• OpenAPI 3.0 官方 GitHub 儲存庫 OpenAPI 計劃
• OpenAPI 3.0 教學概述 IdRatherBeWriting.com
• OpenAPI 視覺文件 APIHandyman.com

Code First「程式碼優先」方法

Code First 方法（通常也稱為「自下而上」方法）是一種更傳統的建立 API 的方法，在製定業務需求之後進行程式碼開發，然後根據程式碼完成 API 文件。

對於許多 API 團隊來說，開始使用 OpenAPI 意味著從「程式碼優先」方法開始，並從現有的 API 集產生定義。當您已經擁有現有 API 時，讓我們探索一些其他流行的產生 OAS 定義的方法。

使用 Inspector 產生 OAS 定義

SwaggerHub Explore 是一種易於使用的開發人員工具，可快速執行任何 API Request 、驗證其 Response 並產生相應的 OpenAPI 定義。使用 SwaggerHub Explore 透過呼叫每個端點並使用關聯的 Response 產生符合OAS 的文件，快速產生現有REST API 的基於OAS 的文件，或將一系列呼叫串在一起，為多個API 端點產生完整的OAS 文件。

使用 SwaggerHub Explore 直接從瀏覽器視窗執行快速 API 呼叫。執行第一次通話後，您可以建立免費帳戶並在 Inspector 中儲存您的通話記錄。

透過 SwaggerHub Explore，您可以為您所呼叫的任何端點自動產生 OpenAPI 文件，從而節省寶貴的開發時間，並讓您的技術編寫人員開始建立出色的文件。

SwaggerHub Explore 與 SwaggerHub 整合，SwaggerHub 是面向團隊的 API 設計和文件平台。此整合可讓開發人員在 SwaggerHub 上自動託管和視覺化其 API 文件，以便內部和外部利害關係人能夠發現和使用 API。

如何從現有 API 產生 OpenAPI

前往 SwaggerHub Explore，並插入您想要記錄的資源的端點。然後，您可以從 SwaggerHub Explore 的歷史記錄部分導覽至右側面板，然後按一下「建立 API 定義」來建立 OAS 定義。

SwaggerHub Explore 的一個很酷的事情是，您可以選擇多個端點並透過 Collection 將它們的文件合併到一個 OpenAPI 檔案中。

您將需要一個 SwaggerHub 帳戶來在 SwaggerHub 上託管產生的 OpenAPI 文件，並在 SwaggerHub Explore 中儲存呼叫歷史記錄。

如果您已有 SwaggerHub 帳戶，則可以使用您的憑證登入 SwaggerHub Explore。當您建立 SwaggerHub Explore 帳戶時，您將自動加入 SwaggerHub 家族。建立帳戶後，您可以隨時隨地輕鬆存取歷史記錄中的所有測試，也可以透過點擊 Inspector 中的按鈕來產生對應的 OpenAPI 規格。

產生的定義將為您的團隊提供符合 OAS 的結構來建立 API 文件。定義到位後，您可以添加重要的詳細資訊，例如：支援的內容類型、描述、範例、身份驗證類型等。

稍後我們將在本資源中更詳細地介紹如何繼續建立 API 文件，但首先，讓我們探討一些用於產生 OAS 定義的其他流行方法。

執行時產生 OAS

swagger-core 是 Swagger 的 Java 實作。目前版本支援 JAX-RS 和普通 servlet。

在此方法中，Swagger/OAS 契約是根據針對各種資源、方法和控制器新增的元資料從 API 產生的。此元資料將在執行時產生契約、客戶端程式碼和其他工件。通常，該元資料採用程式碼註釋的形式。這些工具在針對其資源呼叫各種方法和函數時觸發，並根據 API 中定義的元資料產生 OAS 契約。

為了更好地闡述這個過程，讓我們考慮這樣一種情況：我們必須透過 Jersey 框架從使用 JAX-RS 編碼的 API 產生 OpenAPI 規範。

從現有 API 產生 OAS 文件需要三個步驟：

1. 將依賴項新增至您的應用程式
2. 將 Swagger 核心掛接到應用程式
3. 初始化OAS契約

Swagger 專案使用 Maven 來建置和部署工件，這些工件可在 Maven Central 上找到。這些 Maven 依賴項需要新增到 JAX-RS 編碼的 API 中才能執行 Swagger Core。

典型的 Maven 依賴項如下所示：

<依賴關係>

io.swagger

swagger-jersey-jaxrs

<版本>1.5.12

由於 Jersey REST 框架的主要版本存在差異，使用者應使用 Jersey 2.x 的 swagger-jersey2-jaxrs 依賴項。下一步是將 Swagger Core 連接到您的 API 中。根據 Jersey 在 Web Service 中的設定方式，您可以使用 Spring（Jersey 的容器 Servlet）或手動將 Swagger Core 連接到您的應用程式。

最後，根據前面步驟中新增的程式碼註釋，可以在應用程式執行階段在應用程式中初始化 OAS 定義。產生的 OAS 定義將位於兩個檔案中，分別以 JSON 和 YAML 定義。

以下是一些其他資源，可以幫助您更好地了解此過程：

1. 為 Jersey 專案產生 Swagger
2. 為基於 Spring 的 API 產生 Swagger
3. 為基於 PHP 的 API 產生 Swagger

建置期間的 Swagger 產生

在這個方法中，OAS契約是在API預處理時（即執行階段之前）產生的。針對 API 中各種資源、方法和功能的註解有助於產生 OAS 定義。這些註釋通常採用預先定義的特殊語法，具體取決於您用來產生契約的工具類型。該工具會掃描您的 API 程式碼中的這些特殊註釋，並產生 OAS 契約作為輸出。cakephp-swagger 和 grape-swagger 是在建造期間產生 OAS 契約的工具的突出範例。

任何方法都有缺點和優點。在易用性和速度方面，SwaggerHub Explore 勝過其他產品。只需不到五次點擊，用戶就可以從 SwaggerHub 上託管的現有 API 獲得完全結構化的 OAS 定義。

SwaggerHub Explore 僅產生最終文件的基礎，編寫者仍需要花時間向使用者準確詳細介紹資源、方法以及使用它們的方式。在執行時間產生 OAS 規範會從程式碼中產生更準確的 API 契約，但代價是額外依賴項形式的軟體效能、開發時間，並且可能會增加系統的一些開銷。

相反，在 API 執行之前產生 OAS 契約是一個更輕量級的過程，但產生的 OAS 契約很可能無法準確描述您的 API，因為它必須手動維護。在這兩種方法中，可能需要一些額外的工作來確保產生的 OAS 檔案準確地代表 API 的操作。

根據 OAS 定義記錄 API

無論您採用哪種方法來產生 OAS 定義，仍然需要大量的額外工作來建立 API 文件。

借助 SwaggerHub Explore 或 Swagger Core 等優秀工具，您將擁有一個符合 OAS 的結構，可輕鬆填寫每個 API 端點的重要詳細資訊。產生的文件是 API 技術和互動式文件的基礎。

產生的聯絡人的文件意味著添加有意義的、易於理解的訊息，您的最終使用者可以使用這些資訊來實現 API 成功。OAS 讓您可以描述重要的細節，包括：

• 媒體類型：媒體類型是 Request 或 Response 主體資料的格式。Web Service 操作可以接受和傳回不同格式的資料，最常見的是 JSON、XML 和圖片。
• 端點/資源：這些可能有一個可選的簡短摘要和用於文件目的的較長描述。該資訊應該與該端點中的所有操作相關。描述可以是多行，並支援 Markdown (CommonMark) 進行富文本表示。
• Request 主體： Request 主體通常與「建立」和「更新」操作（POST、PUT、PATCH）一起使用。例如，當使用POST或PUT建立資源時， Request 正文通常包含要建立的資源的表示。
• Response ： API 定義需要指定所有 API 操作的 Response 。每個操作必須至少定義一個 Response ，通常是成功的 Response 。 Response 由其 HTTP 狀態程式碼以及 Response 正文和/或Header中傳回的資料定義。
• 身份驗證：身份驗證是透過使用 securityDefinitions 和 security 關鍵字來描述的。您使用 securityDefinitions 定義 API 支援的所有驗證類型，然後使用 security 將特定驗證類型套用至整個 API 或單一操作。
• 範例：您可以為參數、屬性和物件新增範例，以使 Web Service 的 OpenAPI 規格更加清晰。範例可以透過以某種方式處理 API 的工具和函式庫來讀取。

可以在 OAS 定義中定義的資訊類型只有幾個範例。您可以在此處了解有關使用 OAS 記錄 API 的更多資訊。

請記住，文件是 API 的使用手冊，也是實現 API 業務目標的最大驅動力之一。建立使用者喜歡的 API 文件需要付出努力，但投資將獲得顯著的回報，即出色的開發人員體驗、更輕鬆的實施以及提高 API 的採用率。

在最後一部分中，我們將了解 SwaggerHub 如何協助您使用 OAS 進一步推進 API 文件工作流程。

SwaggerHub 中的 API 設計和文件

文件編制可能是一個棘手的過程。這是一個手動的協作操作，需要作者投入大量的時間、品質和同理心。在從 API 程式碼到文件的整個過程中，最重要的是無縫的工作流程，不會讓您因額外的設定而搞得汗流浹背。通常建議對 API 文件進行獨特的維護和處理，因為文件是使用者和客戶使用您的 API 產品所使用的第一個介面。

SwaggerHub 是一個整合的 API 設計和文件平台，專為團隊建立，旨在推動整個 API 開發工作流程的一致性和規格。它是一個適用於所有工作的專用平台，負責所有設定和託管，使您能夠將文件無縫整合到 API 工作流程中。

從現有 API 程式碼產生 API 契約後，您可以將其匯入 SwaggerHub 中，並繼續您的 API 之旅。互動式文件自動產生並託管在 SwaggerHub 上。可以編輯定義，您的技術作者可以在 API 中添加正確的訊息，從而為使用者提供與其整合所需的資訊。SwaggerHub 的內建工具進一步協助文件流程。

其中一些包括：

• 安全雲端託管：將您的 API 定義儲存在為 API 建置的平台中。SwaggerHub 在整個文件過程中自動儲存您的工作，並提供一個託管文件的中心位置，無需設定伺服器。
• 標準化與治理：讓所有 API 符合您的組織設計標準，以改善使用者的體驗。您的開發人員不再需要參考 wiki 頁面、GitHub 文件或 PDF 來保持 API 之間的樣式一致性，SwaggerHub 會為您標準化它們。
• 協作和問題追蹤：在集中式平台上與多個利害關係人合作。SwaggerHub 為團隊提供了在整個設計和文件流程中進行協作的平台，透過 SwaggerHub 編輯器中的評論即時收集回饋和追蹤問題。
• 部署到 API Gateway ： SwaggerHub 充當 API 定義的真實來源，讓您可以在雲端處理設計和文件工作，並將 OAS 定義無縫推送到 AWS、Microsoft Azure、Apigee 等 API Gateway 。

免費開始！

將 OAS 與 Swagger 工具結合使用可以減輕文件問題，建立自動產生且需要最少維護的互動式文件。需要為現有的一組 API 產生 OpenAPI 定義嗎？嘗試一下 SwaggerHub Explore。

希望標準化您的設計和文件流程？立即開始使用 SwaggerHub。

文章來源: API Documentation Made Easy with OpenAPI & Swagger, SmartBear 2022