API 的好壞取決於其文件。如果人們不知道如何使用，一個很棒的 API 可能會變得毫無用處，這就是為什麼文件對於 API 經濟中的成功至關重要。但是，建立和維護易於閱讀、互動起來愉快，並讓消費者走向成功的良好文件，可能極具挑戰性。建立良好的文件需要付出努力和耐心，但它對 API 的採用和可維護性有直接的影響。透過選擇正確的 API 文件工具，可以讓您的 API 文件更容易管理。 在之前的文章中，我詳細介紹了良好 API 文件的好處。但我們所說的良好文件到底是什麼意思？ 我們詳細介紹了一些好的實務，以幫助您的團隊建立受終端消費者喜愛的良好 API 文件。 但在我們這樣做之前，重要的是要了解一個重要的問題...
您的 API 文件是為誰而寫？
您的 API 旨在解決特定產業中公司面臨的實際問題，並將直接由軟體工程師整合到應用程式中。因此，您的 API 有兩種潛在的受眾，他們將影響您 API 的使用和採用曲線。
決策者
這些人會評估您 API 的服務，並決定開發團隊是否值得花時間探索該服務。他們希望使用您的 API 來解決其產品或服務策略中的潛在挑戰。在許多情況下，他們不會直接使用您的 API，但他們是影響組織決定是否使用它的主要聯絡人。決策者的例子包括技術長或產品經理。
使用者
這些人將直接使用您的 API。他們需要了解您 API 的來龍去脈，以及它如何應用於他們的使用案例。這可能意味著學習如何呼叫和整合您公開的許多或所有資源。它們對於您 API 的永續性至關重要。他們具有分析能力，致力於重要且困難的工程問題，並且時間有限。因此，您的 API 必須易於使用，並且有良好的文件，以便這些使用者可以盡快成功地與您的 API 整合。API 使用者的例子包括前端和後端開發人員。
您的 API 文件需要同時滿足這兩個角色。這可能是一個很難遵循的練習，但它可以確保您的 API 文件是永續且完整的，這可以確保 長期成功和投資報酬率。
API 文件最佳實務
既然我們已經了解了為誰撰寫 API 文件，現在是時候了解好的 API 文件實際上包含什麼了。
API 文件基本章節
有些章節已成為 良好 API 文件的基本章節。這些章節構成了良好文件的基礎，應根據您的 API 預期的產業和消費者類型進行詳細說明。這些章節包括：
驗證
這是關於使用驗證方案開始使用您的 API 的資訊。大多數 API 都有驗證方案，消費者必須先經過驗證才能存取 API。請確保此章節有適當的文件，並引導使用者成功通過 API 的驗證。Bitly 就是一個簡潔驗證文件的絕佳例子。
錯誤訊息
錯誤訊息很重要，因為它們會告訴終端消費者他們以不正確的方式與您的 API 服務整合。說明您的錯誤標準，並在終端消費者收到錯誤時提供如何克服錯誤的解決方案。Mailchimp 在詳細說明消費者可能收到的所有可能錯誤代碼方面做得很好。
資源
請注意您 API 的資源及其相關的請求和回應週期。資源是您 API 的核心組件，使用者將不斷與之互動。列出您 API 公開的所有資源，並了解消費者如何與它們整合。這將讓您更好地了解如何更好地撰寫這些資源下的請求和回應文件。
使用條款
這是消費者和您的組織之間的法律協議，定義消費者應如何理想地使用您的服務。在最佳實務下，包含 API 限制以及條款和條件。還需要清楚地說明約束，以便消費者了解允許哪些 API 使用和實務。以下是 Spotify API 使用條款的一個範例。
變更記錄
詳細說明您 API 的更新和版本，以及這如何影響 API 消費者。這將幫助消費者了解您的 API 的穩定性，並查看是否需要對有效的 API 呼叫進行任何變更。以下是 GitHub API 變更記錄的一個範例。 在您開始撰寫 API 文件之前，先繪製上述章節，對於技術寫作人員來說，是讓他們了解重要優先事項的好方法。
避免使用術語
請記住，許多使用 API 的人員可能並不熟悉您所使用的領域或術語。文件應該要能滿足「非常技術性」的開發人員受眾，以及較不具技術背景的決策者（如產品經理）。技術寫作團隊常犯的一個錯誤是假設他們的受眾都具有完整的技術背景，並且完全了解如何使用 API。 在撰寫文件時，請先使用簡明的英文，並針對每個資源提供易於理解的領域說明。避免使用過多的技術術語，並以能讓剛接觸 API 或該產業的人員也能輕易理解的方式撰寫。 如果您確實有技術或領域特定的術語，請將該特定項目連結到進一步說明這些術語的文件。這將確保您的 API 的清晰度和完整性，幫助使用者了解為什麼存在某些呼叫，並避免在參數、標頭和回應的細節中迷失方向。 一個很好的例子是Stripe 的 API 文件，他們刻意避免使用技術性詞彙。即使有基於領域的術語，也會提供額外的內容來解釋其含義。 YouTube 的 API以其完整性和清晰度而聞名，並且讓開發人員可以輕鬆理解 API 的運作方式。他們還有一個方便的左側導覽面板，方便存取各種資源實作的文件，我個人覺得這非常有幫助。
妥善處理您的請求和回應
請妥善處理您的請求-回應週期的文件。為終端使用者提供過多的資訊永遠不是問題，尤其是在他們嘗試將您的服務整合到其應用程式中時，因此請詳細描述您的請求-回應週期。 記錄您的 API 可能提供的每個呼叫，並提供有關參數和回應的背景資訊。 回應是您的使用者指南，指示他們是否走在正確的軌道上，或提供錯誤訊息以幫助他們成功。您的 API 使用者應該確切知道從成功的 API 呼叫中會得到什麼。針對每個支援的格式，描述完整的範例回應主體。不僅要考慮格式，例如 XML 或 JSON，還要考慮 HTTP 標頭、錯誤代碼和訊息。 參數和回應中的範例也很重要。在您的 API 應該傳回的每個物件中提供範例，以及使用者可以新增以進行成功 API 呼叫的參數範例。 這是另一個Stripe 的絕佳文件範例，以及他們如何詳細說明錯誤回應。另一個關於請求和回應的良好文件範例是Instagram。
利用資源強化您的文件
您可以向使用者提供額外的資訊和資源，以成功使用您的 API。好的 API 文件不僅止於基本內容和 Swagger UI產生，而是要確保您的使用者和潛在客戶能夠儘快成功使用您的 API。您可以使用以下額外資源來補充您的文件：
入門指南
入門指南詳細說明如何快速開始使用您的 API。該指南的重點應放在確保使用者儘快成功使用您的 API，並在整個過程中提供協助。Braintree 是一個很好的入門指南範例，它提供了整合和使用其 API 的良好概述。
SDK 和函式庫
程式碼函式庫可幫助開發人員快速呼叫不同的資源。擁有不同語言的快速且簡便的方法來使用您的 API，有助於開發人員更自在地使用 API。SDK 很難建置，而且對於發布並非至關重要，但可以大大提升 API 的採用率。如果您的商業模式是公開的開放 API 模式，那麼擁有 SDK 是與開發人員社群互動的好方法。在這種情況下，如果開發人員發現您的 SDK 和 API 具有價值，他們很有可能會在其基礎上進行建置，或新增更多函式庫。Swagger Codegen專案可協助團隊直接從其 API 文件快速產生 SDK。
互動式主控台
鼓勵潛在客戶立即使用 API 主控台測試他們在 API 文件中讀到的內容。實驗是強大的，而主控台讓入門變得容易，且對使用者而言風險有限。建立一個主控台或沙箱環境讓使用者與您的 API 互動相對簡單，但對於幫助開發人員視覺化地了解您的 API 的價值，可能會產生很大的作用。許多公司，例如GitHub和Microsoft，都提供互動式主控台來試用其 API 產品。
良好的 API 文件需要努力，但這是值得的
我們始終相信 API 文件是推動您的 API 成長和成熟的強大工具。它是使用者在使用 API 時獲得良好開發人員體驗的基礎。 希望透過以上提示，您能更輕鬆地撰寫好的文件。熱門的開放原始碼描述格式，如OpenAPI 規格和商業平台，如SwaggerHub，可讓團隊自動化文件流程，並致力於提供良好的整體 API 使用體驗。 您可以在此處探索 SwaggerHub 的 API 文件功能，或免費自行試用。
網路研討會：將企業轉型為 API 平台的經驗教訓
您的數位轉型工作是否正帶領您的企業朝正確的方向發展？在 4 月 10 日，我們將舉辦一個免費網路研討會：將企業轉型為 API 平台的經驗教訓。本課程的重點是從與款待業、貸款發放和金融科技領域的各個組織合作開發和部署其 API 平台中吸取的經驗教訓。這些企業實施了 API 優先設計、聯合治理和 API 管理層，作為其整體平台策略的一部分。我們將探討哪些方法有效、哪些方法無效，以及簡化您的轉型計畫的訣竅。將討論的主題
- 開發有效的 API 程式，以促進內部重複使用和蓬勃發展的合作夥伴計畫
- 實施 API 治理的技術，包括探索集中式與聯合式治理
- 微服務和模組化軟體設計如何改變當今企業的文化
- 透過開發出色的入口網站和開發人員支援流程，增加 API 上線和採用率
- 透過以 API 為中心的方法加速企業轉型計畫的訣竅
立即註冊 