良好的使用者體驗是使用任何產品的關鍵，API 也是如此。用於使用 API 的介面越好，實現業務和技術目標的可能性就越高。
自從行動和雲端運算問世以來，API 已成為主流，越來越多的公司和組織了解建立 API 的商業價值。隨著越來越多的網路服務出現，對於採用這些服務來說，擁有清晰的 API 文件變得非常重要。
API 文件是成功使用並與 API 整合所需資訊。這可以是技術寫作、程式碼範例和範例的形式，以便更好地了解如何使用 API。簡潔明瞭的文件 — 讓您的 API 使用者能夠快速將其導入到他們的應用程式中 — 對於想要推動 API 採用的組織來說，已不再是可選項。
為什麼文件很重要
ProgrammableWeb 的一項調查發現，API 使用者認為完整且準確的文件是他們在 API 決策中最重要的因素，甚至超過價格和 API 效能。
良好的文件可以加速開發和使用，並減少回答支援電話所花費的金錢和時間。文件是整體使用者體驗的一部分，也是提高 API 成長和使用的最大因素之一。
API 文件的挑戰
與許多其他產品一樣，API 在開發和發布週期中往往會快速發展。為您的開發團隊和最終使用者維護和更新此文件，以便他們有效地使用 API，這變成了一個困難的過程。如果您使用靜態文件（如 .pdf）向最終使用者提供文件，則尤其如此。第二個問題是促進多個網路服務之間的互動。應用程式由不斷相互溝通和互動的多個服務組成。
隨著 RESTful 服務的數量不斷增加，用於實作它們的程式設計語言也隨之增加，使得它們難以溝通。API 文件可以被認為是使用 API 的介面，因此，需要促進這些不同網路服務之間的互動。普通的 API 介面，無論是文字文件，還是其他像 Javadocs 的介面，都不能讓它們相互溝通。這些挑戰以及其他 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 的功能、請求參數和回應物件，而沒有任何程式碼實作的指示。用 OAS 定義的網路服務可以相互溝通，而不管它們是用哪種語言建置的，因為 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 之前，嘗試 API 的每個資源並熟悉它。使用 SwaggerHub 平台，組織還可以為其外部使用者提供受控存取。
- 為您的 API 建立測試：您的 OAS 定義提供了一個合約，描述當有人呼叫您的 API 時，成功回應會是什麼樣子。此合約也可以重新用於產生測試案例，這可以大幅減少團隊測試 API 所需的設定量。
- 產生實作程式碼和 SDK：除了產生文件外，OpenAPI 定義還可以透過為 API 建立程式碼框架實作和 SDK 來加速開發。API 定義檔案可以匯入許多不同的工具中，例如 Swagger Codegen 和 SwaggerHub，以使用多種不同的語言（例如 Java、Scala 和 Ruby）建立這些存根程式碼。
既然我們已經介紹了為什麼您的團隊應該將 OAS 和 Swagger 工具納入您的 API 開發工作流程，那麼下一個問題是您實際上如何開始？在下一節中，我們將更仔細地探討開始使用 OAS 的不同方法。
OpenAPI 的方法
在建立 OAS 定義時，出現了兩種重要的思想流派：API 開發的「先設計」和「先程式碼」方法。
「先設計」方法提倡在編寫任何程式碼之前先設計 API 的合約。這是一種相對較新的方法，但正在快速普及，尤其是在使用 OpenAPI 的情況下。在「先設計」方法中，API 合約充當中心草案，使您的所有團隊成員在 API 的目標以及如何公開 API 的資源方面保持一致。
在編寫任何程式碼之前發現設計中的問題，比在實作完成後發現問題更有效率和簡化。
如果您的團隊準備好轉換到「先設計」方法，您首先需要熟悉編寫 API 定義。以下是一些資源可協助您開始此流程
「先程式碼」方法
「先程式碼」方法（也稱為「由下而上」方法）是一種更傳統的 API 建置方法，在制定業務需求之後進行程式碼開發，然後從程式碼中完成 API 的文件。
對於許多 API 團隊來說，開始使用 OpenAPI 意味著從「先程式碼」方法開始，並從現有的 API 集中產生定義。讓我們探討一些在您已經有現有 API 時產生 OAS 定義的其他常用方法。
使用 Inspector 產生 OAS 定義
Swagger Inspector 是一個易於使用的開發人員工具，可快速執行任何 API 請求、驗證其回應並產生對應的 OpenAPI 定義。使用 Swagger Inspector，透過呼叫每個端點並使用相關的回應來產生符合 OAS 的文件，為現有的 REST API 快速產生基於 OAS 的文件，或將一系列呼叫串聯起來，為多個 API 端點產生完整的 OAS 文件。
使用 Swagger Inspector，直接從瀏覽器視窗執行快速 API 呼叫。在執行第一次呼叫後，您可以建立一個免費帳戶，並將您的呼叫歷史記錄儲存在 Inspector 中。
透過 Swagger Inspector，您可以自動為您呼叫的任何端點產生 OpenAPI 檔案，從而節省寶貴的開發時間，並讓您的技術寫手開始編寫出色的文件。
Swagger Inspector 與 SwaggerHub 整合，SwaggerHub 是團隊使用的 API 設計和文件平台。此整合讓開發人員能夠在 SwaggerHub 上自動託管和視覺化他們的 API 文件，以便內部和外部的利益相關者能夠探索和使用 API。
如何從現有 API 產生 OpenAPI
前往Swagger Inspector，並插入您想要記錄的資源端點。然後，您可以從 Swagger Inspector 的「歷史記錄」部分導覽至右側面板，並點擊「建立 API 定義」以建立 OAS 定義。
Inspector 最棒的地方在於，您可以選擇多個端點，並透過集合將其文件整合到一個單一的 OpenAPI 檔案中。
您需要一個 SwaggerHub 帳戶才能在 SwaggerHub 上託管產生的 OpenAPI 檔案，以及在 Swagger Inspector 中儲存您的呼叫歷史記錄。
如果您已經有 SwaggerHub 帳戶，則可以使用您的憑證登入 Swagger Inspector。當您建立 Swagger Inspector 帳戶時，您會自動加入 SwaggerHub 系列。建立帳戶後，您可以隨時隨地輕鬆存取歷史記錄中的所有測試，也可以在 Inspector 中按一下按鈕，產生對應的 OpenAPI 規格。
產生的定義將為您的團隊提供一個符合 OAS 的結構，以建構您的 API 文件。有了這個定義，您可以新增重要的詳細資訊，例如：支援的內容類型、描述、範例、驗證類型等等。
我們將在本資源稍後更詳細地介紹如何繼續建構您的 API 文件，但首先，讓我們探討其他幾種產生 OAS 定義的熱門方法。
執行階段期間的 OAS 產生
Swagger-core 是 Swagger 的 Java 實作。目前版本支援 JAX-RS 和純 Servlet。
在此方法中，Swagger/OAS 契約是根據針對各種資源、方法和控制器新增的中繼資料，從 API 產生的。此中繼資料將在執行階段產生契約、用戶端程式碼和其他成品。通常，此中繼資料將以程式碼註解的形式存在。當針對其資源呼叫各種方法和函數時，工具會觸發，並從 API 中定義的中繼資料產生 OAS 契約。
為了更好地闡述這個過程，讓我們考慮一個案例，我們必須從使用 JAX-RS 和 Jersey 架構編碼的 API 產生 OpenAPI 規格。
從現有 API 產生 OAS 文件需要三個步驟
- 將相依性新增至您的應用程式
- 將 Swagger Core 連接到應用程式
- 初始化 OAS 契約
Swagger 專案使用 maven 來建置和部署成品，可在 Maven Central 上取得。這些 maven 相依性需要新增到您的 JAX-RS 編碼 API 中，才能執行 Swagger Core。
典型的 maven 相依性看起來會像這樣
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-jersey-jaxrs</artifactId>
<version>1.5.12</version>
</dependency>
由於 Jersey REST 架構的主要版本存在差異，使用者應使用 swagger-jersey2-jaxrs 相依性來處理 Jersey 2.x。下一步是將 Swagger Core 連接到您的 API。根據 Jersey 在您的 Web 服務中的設定方式，您可以使用 Spring、Jersey 的容器 Servlet 或手動方式將 Swagger Core 連接到您的應用程式。
最後，根據前述步驟中新增的程式碼註解，可以在應用程式的執行階段內初始化 OAS 定義。產生的 OAS 定義將分為兩個檔案，分別以 JSON 和 YAML 定義。
以下是一些額外的資源，可協助您更瞭解此過程
- 為 Jersey 專案產生 Swagger
- 為基於 Spring 的 API 產生 Swagger
- 為基於 PHP 的 API 產生 Swagger
建置時期的 Swagger 產生
在此方法中，OAS 契約是在預先處理 API 時產生的，也就是在執行階段之前。API 內針對各種資源、方法和函數的註解有助於產生 OAS 定義。這些註解通常採用預先定義的特殊語法，具體取決於您用來產生契約的工具類型。該工具會掃描您的 API 程式碼以尋找這些特殊註解，並產生 OAS 契約作為輸出。Cakephp-swagger 和 grape-swagger 是在建置時期產生 OAS 契約的著名工具範例。
任何方法都有優缺點。就易用性和速度而言，Swagger Inspector 勝過其他方法。使用者只需按不到五次按鈕，就可以從他們託管在 SwaggerHub 上的現有 API 取得完整結構化的 OAS 定義。
Swagger Inspector 僅產生最終文件的基礎，寫手仍然必須花時間準確詳細地說明資源、方法以及您如何將它們用於消費者。在執行階段產生 OAS 規格會從程式碼產生更準確的 API 契約，但代價是增加軟體負載，例如額外的相依性、開發時間，並可能為系統增加一些負擔。
相反地，在 API 的執行階段之前產生 OAS 契約是一個更輕量的過程，但是產生的 OAS 契約很可能無法準確描述您的 API，因為它必須手動維護。在這兩種方法中，都可能需要一些額外的工作，以確保產生的 OAS 檔案準確地表示您的 API 操作。
從 OAS 定義記錄 API
無論您採用哪種方法產生 OAS 定義，仍然需要大量額外的工作來建構您的 API 文件。
有了像 Swagger Inspector 或 Swagger Core 這樣出色的工具，您將有一個符合 OAS 的結構，讓您可以輕鬆填寫每個 API 端點的重要詳細資訊。產生的檔案是您的 API 技術和互動式文件的基礎。
從產生的契約撰寫文件，將表示新增有意義、易於理解的資訊，您的終端消費者可以使用這些資訊來實現 API 的成功。OAS 讓您可以描述重要的詳細資訊，包括
- 媒體類型：媒體類型是請求或回應主體資料的格式。Web 服務操作可以接受和傳回不同格式的資料，最常見的是 JSON、XML 和影像。
- 端點/資源：這些端點/資源可能會包含用於文件用途的簡短摘要和較長的描述。此資訊應該與此端點中的所有操作相關。描述可以是多行的，並支援 Markdown (CommonMark) 以呈現豐富的文字。
- 請求主體：請求主體通常與「建立」和「更新」操作 (POST、PUT、PATCH) 一起使用。例如，當使用 POST 或 PUT 建立資源時，請求主體通常包含要建立的資源的表示。
- 回應：API 定義需要指定所有 API 操作的回應。每個操作都必須至少定義一個回應，通常是成功的回應。回應由其 HTTP 狀態碼以及回應主體和/或標頭中傳回的資料定義。
- 驗證：驗證是使用 securityDefinitions 和 security 關鍵字來描述的。您可以使用 securityDefinitions 來定義 API 支援的所有驗證類型，然後使用 security 將特定的驗證類型套用於整個 API 或個別的操作。
- 範例：您可以將範例新增至參數、屬性和物件，以使您的 Web 服務 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 閘道：SwaggerHub 作為您的 API 定義的真實來源，讓您可以在雲端中處理您的設計和文件工作，並將您的 OAS 定義無縫推送至 API 閘道，例如 AWS、Microsoft Azure、Apigee 等。
免費開始使用！
使用 OAS 和 Swagger 工具可以減輕文件方面的顧慮，建立自動產生的互動式文件，並且只需最少的維護。需要為現有的 API 集產生 OpenAPI 定義嗎？試用 Swagger Inspector。
想要將您的設計和文件流程標準化嗎？立即開始使用 SwaggerHub。