我們正處於多平台經濟中，而 API 是數位領域的黏合劑。平台是一種產品，使用者可以擴展該產品以造福其他使用者。任何產品都可以透過提供使用者在其上新增服務和功能的方法來成為平台。API 是平台經濟的促成者，允許使用者在現有產品之上增強和新增服務。當產品轉變為平台時，它會採用一種新型的使用者：第三方開發人員。
迎合開發人員是很棘手的。他們是分析性的、精確的，並且正在嘗試使用您的 API 來解決重要問題。他們希望了解如何有效地使用您的 API，這就是 API 文件發揮作用的地方。在這篇部落格文章中，我們將探討撰寫 API 文件的意義，以及為什麼擁有良好的 API 文件很重要。
什麼是 API 文件？
API 文件是技術內容交付物，其中包含有關如何有效使用 API 並與之整合的說明。它是一本簡潔的參考手冊，其中包含使用 API 所需的所有資訊，以及有關函式、類別、傳回類型、引數等的詳細資訊，並提供教學和範例。API 文件傳統上是使用一般內容建立和維護工具以及文字編輯器完成的。
像是 OpenAPI/Swagger 規格 之類的 API 描述格式已將文件流程自動化，使團隊更容易產生和維護它們。 
第三方開發人員是您 API 的主要使用者，他們正忙於解決複雜的程式設計挑戰。
您的 API 對於技術使用者而言是一種達到目的的手段，他們希望盡快整合以在軟體開發中前進，這表示他們應該立即了解您的 API 的價值和用法。開發人員在發現、學習使用並最終與 API 整合時的整體體驗稱為 開發人員體驗 (DX)。API 文件是良好 DX 的關鍵。
為什麼要撰寫 API 文件？
在 API 生命週期中的所有階段中，文件可能是成長最快的領域。隨著文件周圍的工具生態系統，情況尤其如此。值得注意的是這種趨勢，因為文件傳統上是開發人員在啟動程式碼時很少關注的事情。
事實上，實作程式碼比撰寫良好的文件容易得多。但這是因為它對採用和使用有直接影響。您可以擁有最好的功能產品，但如果沒有人知道如何使用它，就不會有人使用它。文件是良好開發人員體驗的基礎。
提升使用者採用率
採用模式已在技術領域轉向開發人員。擁有良好 API 文件的一個重要原因是，它可以改善開發人員使用您的 API 的體驗，這與 API 採用率有直接關係。人們會採用他們喜歡使用的產品，您的 API 也是如此。如果您把文件做好，就會有更多的人很容易在您的服務中找到價值，從而 實現更好的成長和採用。
提高意識
使用者產生使用者。網路效應是一種現象，當更多人使用某種服務或產品時，該服務或產品會變得更有價值。您滿意的消費者將是 API 最強大的擁護者。隨著越來越多的使用者採用您的 API 並達到臨界質量，您滿意的消費者可能會增加傳教和口耳相傳的宣傳，從而產生網路效應。就像我們在 SmartBear 說的那樣，可見的 API 會被重複使用，而不是重新發明。
想想您自己的體驗 - 我們總是會提高我們使用過的優良產品的知名度，開發人員也是如此。如果他們可以輕鬆快速地學習使用您的 API，他們將會是您最大的支持者。
節省支援時間和成本
除了提高 API 的知名度和採用率之外，良好的文件還可以減少新使用者入門所花費的時間，無論是內部開發人員還是外部合作夥伴。
不良或沒有文件表示會有更多沮喪的使用者依賴您的團隊來了解如何使用您的 API。相反地，當您讓使用者在實作 API 之前嘗試 API，並為他們提供詳細的文件以開始使用時，您將節省您的團隊無數小時的回應支援電子郵件和電話。
更容易維護
最後，文件有助於產品的良好維護。它可以幫助您的內部團隊了解您的資源、方法及其相關請求和回應的詳細資訊，從而加快維護和更新速度。
如何撰寫 API 文件
有很多方法可以開始撰寫 API 文件。這實際上取決於您已確定的 API 設計方法。就像我們之前說的，如果您是從頭開始建構 API，OpenAPI 和 Swagger 工具已協助將文件流程自動化，這讓您或您的團隊更容易維護和更新您的文件。如果您採用 API 設計的「程式碼優先」方法，使用 Swagger Inspector 建立 API 文件會變得輕而易舉。
此工具是免費的雲端 API 測試和文件產生工具。Swagger Inspector 允許您使用任何 API 並自動產生 OpenAPI 文件。這對於希望使用 OpenAPI 規格進行標準化的個人尤其有用。以下是如何使用 Swagger Inspector 產生文件的快速教學。 立即試用 Swagger Inspector！
總結
文件是使用 API 時獲得良好體驗的關鍵。它不僅可以讓消費者滿意，還可以讓您的 API 採用率提高。像是 OpenAPI 規格等流行的開源描述格式和像是 SwaggerHub 等商業平台，讓團隊可以將文件流程自動化，並致力於建立良好的 API 使用整體體驗。
感謝您的閱讀！正在尋找更多 API 資源嗎？訂閱 Swagger 電子報。每月接收包含我們最佳 API 文章、培訓、教學等的電子郵件。訂閱