2、讓更多人使用您的產(chǎn)品
沒有人會喜歡用戶體驗(yàn)差的產(chǎn)品。在提供卓越的開發(fā)人員體驗(yàn)方面，API 文檔已被證明是最不可或缺的要素之一。由于API文檔的有效性與采用率成正比，因此擁有一份簡單明了、易于理解的API用戶手冊會讓更多人使用您的API。

3、廣泛傳播
與其他產(chǎn)品一樣，API 也可以從品牌擁護(hù)者那里獲益。當(dāng)您提供詳盡易懂的 API 文檔時，會有更多人使用您的 API。滿意的客戶最有可能成為您產(chǎn)品的擁護(hù)者。因此，出色的文檔會讓客戶更滿意，反過來，客戶又會通過口碑向他們的朋友和熟人傳播您的產(chǎn)品。

API文檔由誰編寫？

API是由軟件開發(fā)人員編寫的，由于軟件開發(fā)人員直接參與了API的建設(shè)和使用，所以他們更容易創(chuàng)建API接口文檔，確定API協(xié)議、API通訊方式、API交互方式等。

軟件開發(fā)人員編寫API文檔的缺點(diǎn)是，他們從一個非常技術(shù)性的角度來寫，這可能使文檔相當(dāng)難以理解。

因此，一個好的選擇是將API文檔的是由多種角色協(xié)作來完成：軟件開發(fā)人員撰寫API接口文檔，產(chǎn)品經(jīng)理撰寫API產(chǎn)品介紹，技術(shù)作家撰寫API使用部分，將內(nèi)容寫作和技術(shù)知識的專業(yè)知識結(jié)合起來，從軟件開發(fā)人員那里了解API，然后創(chuàng)建教程、例子和其他內(nèi)容。最終形成信息豐富的、可以理解的API文檔。

什么樣的API文檔是好文檔？

評估一份API文檔的好壞，可以從以下幾個方面進(jìn)行：

• 目標(biāo)受眾是否明確，定義 API 文檔的受眾群體，包括開發(fā)者、系統(tǒng)管理員等，確保文檔內(nèi)容滿足他們的需求。
• 是否遵循統(tǒng)一的API描述標(biāo)準(zhǔn)，使用一致的標(biāo)準(zhǔn)，可被交互式文檔或API管理工具整合，使開發(fā)者能夠直觀地瀏覽、測試和理解 API 的功能。
• 是否準(zhǔn)確的產(chǎn)品定義，API接口不僅是一個技術(shù)文檔，它同時是一份API產(chǎn)品說明書，模糊的API文檔會讓使用者搞不清API產(chǎn)品能夠解決的問題。
• 是否提供實(shí)際的使用示例，通過實(shí)際的代碼示例演示 API 的使用方式，幫助開發(fā)者更容易理解和實(shí)踐。
• 是否能成搖錢樹（增值選項(xiàng)），一篇好的API文檔會變成搖錢樹，幫助企業(yè)實(shí)現(xiàn)二次營收增長。

API文檔與安全性是啥關(guān)系？

API文檔在網(wǎng)絡(luò)安全中的作用非常重要，有兩個很好的例子，說明糟糕的文檔對數(shù)據(jù)泄露和暴露產(chǎn)生了影響。

• Uber 2016 年的數(shù)據(jù)泄露事件，5700 萬用戶和司機(jī)的個人信息遭到泄露。這次漏洞部分歸咎于 API 密鑰的處理方式問題，特別是 Uber AWS 賬戶的 API 密鑰可通過其 GitHub 中的私人存儲庫獲取。
• 大約從 2014 年開始，劍橋分析公司濫用 Facebook 的 API，在未經(jīng)用戶同意的情況下獲取了數(shù)百萬 Facebook 用戶的數(shù)據(jù)。問題的部分原因是 API 使用政策和控制不力，尤其是合作伙伴文檔中的這些政策不夠明確。

反之，好的API文檔能夠大幅提升API安全性，有助于API審計(jì)和合規(guī)，詳細(xì)請閱讀API文檔與API安全。

API文檔與代碼自動生成是啥關(guān)系？

使用者的編程語言多種多樣（TypeScript、Java、Go、Swift、ObjectiveC、Kotlin、Dart、C++、C#、Rust 等 130 種語言和框架），開發(fā)者完全自己維護(hù)API客戶端代碼已經(jīng)不太現(xiàn)實(shí)，因此基于API描述文檔來生成API客戶端代碼，甚至API測試用戶、API服務(wù)端偽代碼、數(shù)據(jù)模型代碼等都成為一種剛需。

API文檔存在多種版本時，這種自動維護(hù)API客戶端代碼的能力顯得更為重要。

API文檔需要專業(yè)的API文檔工具來支持？

需要。

• API描述規(guī)范具有一定的復(fù)雜性，完全手寫不太現(xiàn)實(shí)
• API文檔的維護(hù)是一個巨大的工程，自己編寫文檔框架成本太高，且未必好用
• API文檔工具一般都集成了API安全審查能力，可以快速發(fā)現(xiàn)API安全漏洞
• API客戶端代碼的維護(hù)需要自動化工具平臺來支持

擴(kuò)展閱讀

推薦10+款常用的API文檔工具

9 款適用于小型企業(yè)的一體化API管理工具 ，您不再需要單獨(dú)的API文檔工具