像是 OpenAPI (Swagger) 的描述格式，以及像是 Swagger UI 的開放原始碼實作，改變了 API 團隊對 API 文件的看法。 透過提供一種格式來定義您的 API 操作，使其既可供人類閱讀又可供機器閱讀，然後將這些操作視覺化，讓終端消費者可以與 API 的不同端點互動，這些工具消除了手動維護 API 文件的需求。
這為 API 團隊帶來了明顯的好處。
維護 API 的準確且最新的文件一直是一個痛苦的過程。即使是那些有幸聘請技術寫手來撰寫 API「使用手冊」的組織和團隊，在更新具有新 API 版本的檔案時仍然面臨問題，另一個主要好處是描述格式及其支援工具可協助產生 API 文件的速度。 Swagger UI 是這方面的最佳範例，它允許使用者從基本 API 設計自動產生 API 文件，從而節省數小時的時間和開發人員資源。
在過去幾個月中，SwaggerHub 團隊參加了諸如 IBM Interconnect、Microsoft Build 和 DockerCon 2017 等活動，並多次從開發人員、技術寫手、API 設計師、DevOps 和其他軟體專業人員那裡聽說 Swagger UI 在產生有用的 API 文件方面的效率如何。 但是，我們從這些對話中學到的教訓之一是，API 消費者對 API 文件的期望更高，尤其是在 API 經濟的競爭生態系統中。
畢竟，雖然為您的 RESTful API 產生介面是向終端消費者提供文件的好第一步，但這只是您可以做到的讓人們了解如何有效使用您的 API 的開始。
您的 API 文件可能遺漏的內容
為終端消費者產生一個可以與您的 API 互動的 UI 是提供出色的 API 開發人員體驗的關鍵第一步。但是在當今的現代 API 經濟中，API 在業務和策略成長中扮演著核心角色，文件需要超越基本的 UI。
產生此 UI 的目標是提供一個視覺資源，供終端消費者使用，以輕鬆了解如何使用您的 API。這是使用您的 API 的使用手冊，如果此使用手冊不完整且對消費者沒有幫助，則可能會直接損害您的消費者的開發人員體驗並破壞您的 API 計畫的成功。因此，開始思考如何改進基本 Swagger UI 和 API 文件非常重要，這最終會在使用 API 時帶來良好的開發人員體驗。
以下是您的 API 文件可能缺少的一些關鍵部分
1. 概觀區段
如果您只是為您的 API 產生一個基本的 UI，則您的文件很有可能會缺少有用的描述，讓使用者可以輕鬆了解您的 API 的用途以及他們為什麼首先要使用它。提供使用者需要了解您的 API 價值的必要資訊，並提供入門簡介。這是您 API 的潛在消費者的第一個入口點，因此請務必專注於您的 API 提供的價值 — 它做什麼、解決什麼問題，以及終端消費者從使用您的 API 中應該期望獲得什麼結果。詳細說明本節時，請考慮您的消費者嘗試解決的挑戰。這樣，概觀區段的訊息才能真正引起目標受眾的共鳴。
以下是我們最近關於 API 開發人員體驗的 SwaggerHub 線上研討會中的範例描述： 
入門指南
入門指南可以提供有關存取 API 金鑰或客戶端權杖的資訊，以及使用 API 的條款。除了 API 的 UI 之外，您還可以包括指向其他參考資料的連結，以及如何聯絡您的團隊以尋求支援或分享意見回饋的詳細資訊。本指南應引導您的消費者走向成功。我們建議起草指南，可以協助消費者在 5 分鐘內了解您的 API 的價值。請考慮 SwaggerHub 客戶 Bandsintown 的此範例，該客戶在其網站上發布來自 SwaggerHub 的公共 API 文件。 
入門指南提供了在 Bandsintown API 上啟動並執行所需的必要指導。 還有來自 Braintree 和 YouTube 等公司的有用範例，這些公司建立了完整的說明區段，讓開發人員了解如何使用其 API。
請求-回應週期的說明
許多 API 團隊在描述 API 端點時會做到最基本的要求，產生可視化 API 所需的基本框架，而沒有新增任何真正的詳細資訊來協助使用者了解如何使用它們。這在以前可能有效，但在當今每天都有新的 API 和解決方案出現的競爭環境中，使用者有多種選擇，他們應該得到完整性。
以每個支援的格式描述完整的範例回應主體。這不僅包括 XML 或 JSON 資料格式，還包括 HTTP 標頭、錯誤代碼和訊息。提供過多的資訊來協助潛在客戶或終端消費者學習如何使用您的 API 永遠不是一個壞主意。請記住，良好 API 文件的目標是為您的目標受眾提供了解如何使用您的 API 的必要資訊。您應該包含詳細的描述，並在必要時提供使用範例。
如果您有技術或領域特定的術語，請將該特定項目連結到進一步說明這些術語的文件。這些策略將確保您的 API 清晰且結構良好，以及某些呼叫存在的原因，而不會迷失在參數、標頭和回應的細節中。
SDK 和程式碼庫的連結
SDK 函式庫能幫助使用者更快地整合您的 API。它們非常適合讓您的使用者能夠輕鬆使用 API 的操作，並在其之上建構豐富的功能和應用程式。如果您已經使用 OpenAPI 規範定義了您的 API，您可以使用像 SwaggerHub 這樣的平台來產生伺服器端程式碼和用戶端 SDK，以幫助提高 API 的採用率。
只需按一下，SwaggerHub 就能產生 HTML 範本，其中包含您 API 的文件和 6 個用戶端 SDK 使用範例，方便您的開發人員入口網站使用，讓您的開發團隊可以非常輕鬆地自訂、互動和使用。您隨時可以使用 SwaggerHub 內建的程式碼產生器，將 SDK 擴展到 30 多種語言。 
使用 SwaggerHub 讓您的 API 文件發揮更大作用
如果您已經使用 Swagger 為您的 API 產生互動式 UI，那麼您已經準備好使用像 SwaggerHub 這樣的 API 文件工具將您的 API 文件提升到新的層次。SwaggerHub 處理了所有基礎架構考量和安全性實作，讓組織能夠無縫協作，並建立消費者和開發團隊都會喜歡的優質 API 文件。深入了解如何使用 SwaggerHub 撰寫 API 文件。或立即免費試用 SwaggerHub。