爲何須要使用api文檔

什麼是API文檔？

API文檔是一份可交付的技術內容，其中包含有關如何有效使用和集成API的說明。這也是一本簡單明瞭的參考手冊，編寫了使用API所需的全部信息，以及有關功能、返回類型、參數等詳細信息，並提供了教程和示例支持。

API文檔一般由常規的內容建立和維護工具以及文本編輯器完成的。例如 Swagger、eolinker規範之類的API描述格式已經自動化了文檔處理過程，從而使團隊能夠更輕鬆地生成和維護API。

第三方開發人員是API的主要用戶，正忙於解決複雜的編程難題。API是技術用戶達到目的的一種手段，他們但願儘快集成推動他們的軟件開發，這意味着他們應該快速瞭解你的API的價值和用途。開發人員在發現、學習使用並最終與API集成時所積累的經驗稱爲開發人員經驗。API文檔是得到出色開發人員經驗的關鍵。

爲何要使用文檔API？

在API生命週期的全部階段中，文檔多是增加最快的領域。對於圍繞文檔的工具生態系統尤爲如此。注意到這一趨勢頗有趣，由於從傳統上講，文檔是開發人員在編寫代碼時不多關注的東西。實際上，實現代碼比編寫良好的文檔要容易得多。

提升用戶使用率
擁有良好的API文檔的一個重要緣由是，它改善了開發人員使用API的體驗，這與API的採用直接相關。若是API文檔正確無誤，那麼更多的人將很容易在提供的服務中發現價值，從而能夠更好地發展和採用。

節省支持時間和成本
好的文檔還能夠減小新用戶（不管是內部開發人員仍是外部合做夥伴）的培訓時間。糟糕的文檔或者沒有文檔意味着更多用戶依賴於團隊培訓來理解如何使用API。
相反，當你在用戶使用API以前先試用API，而且配備詳細的api文檔，將爲團隊節省大量時間來回覆電子郵件和電話。

易於維護
文檔可帶來良好的產品維護。它能夠幫助內部團隊瞭解資源、方法及其相關請求和響應的詳細信息，從而能夠更快地進行維護和更新。

結語

使用API時，文檔是得到良好體驗的關鍵。它不只能提升用戶滿意度，還能夠提升API的使用率。在提供優秀的API文檔的條件下，api管理平臺還支持測試、監控等功能，讓用戶在使用API方面得到出色的體驗。
原文：https://dzone.com/articles/what-is-api-documentation-and-why-does-it-matter
翻譯：www.eolinker.com