什麼是好用的 API 文檔

來自專欄 餓了么前端

對程序員來說，API 文檔是再熟悉不過的東西，幾乎每天都要打交道。在大多數開發團隊中，只要有前後端的合作，API 文檔就會作為兩方溝通的橋樑而存在。API 文檔是後端對所提供服務的說明，前端開發者通常作為 API 文檔的消費者，下面我就從一個消費者的角度談談什麼樣的 API 文檔是好用的。

API 文檔是什麼？

簡單來說它就是對所有 API 的調用和其中涉及到的參數的清晰的解釋說明。說具體一點，就是每個 API 可以做什麼，以及對 API 中每個參數的解釋，包括它們的類型、格式、可能的取值、驗證規則、是否必需等。

API 文檔有什麼？

歡迎頁面

常常會有人忽略了這個頁面的重要性，當然，如果是內部的項目，歡迎頁面有時不是那麼重要，但 API 文檔如果是對外的，例如每個公司的開放平台文檔，那麼一個內容詳盡的歡迎頁面甚至可以決定一個開發者是否願意接入你們的平台。

歡迎頁面可以包含的內容有：

• 產品提供了哪些 API，可以用來做什麼
• API 是如何工作的，技術架構的簡單介紹
• 新手指南，從零開始到建立一個可用的 API 調用過程的步驟，包括建立賬戶、設置開發環境、鑒權、實際運行等幾個方面

（Spotify 的 API 文檔歡迎頁面）

包含完整上下文的示例

設想一下我們讀 API 文檔的場景，我們會像讀小說一樣從頭開始看嗎？大多數情況下並不會，一般我們會從 API 列表裡面根據名稱直接跳轉到我們需要查看的 API 處直接閱讀。因此，對於內容的組織，在每個 API 的解釋中都要包含所有必需的信息和相關的解釋說明。例如 GitHub 的 REST API 文檔中的 commits 一節，每個 API 的部分，詳細給出了：

• 返回值，路徑規則，參數解釋（參數名、類型和描述）
• 輸入參數的示例
• 返回值的示例
• 對於一些特別的概念，給出了跳轉鏈接便於查看

示例的常見類型

• 自動生成的代碼示例

通過一些工具可以從項目的代碼中直接生成文檔示例，例如 api blueprint。這樣做的好處是，當修改源碼的同時，文檔內容也會同步更新，避免了文檔更新不及時的問題。不過建議不要完全依賴自動化的工具，在生成內容後還是需要手動補充必要的說明，使得文檔內容更加易懂。

• 示例項目

沒有什麼比 API 在真實項目中的應用更直觀的了，通過真實的示例項目代碼，可以幫助用戶理解每個 API 是如何使用，如何聯繫的。通常可以在文檔中給出指向示例項目 GitHub 倉庫的鏈接，代碼量不大的話，也可以直接貼在文檔中。

• 支持多語言的客戶端模塊

顧名思義，這種方式是將 API 的調用，包括鑒權、配置等過程都封裝在客戶端模塊中，用戶直接在項目中引用並調用封裝好的方法即可。這種方式能簡化客戶端調用 API 的工作複雜度，但同時會增加 API 提供者的工作量，在更新後端服務的同時客戶端模塊也需要同步更新。例如 GitHub 就為不同語言提供了客戶端模塊。

錯誤相關信息

另外，在調試過程中一旦出現錯誤，關於錯誤信息的詳細文檔可以減少解決錯誤的難度，其中應該包含：

• 錯誤的狀態碼以及描述
• 引起錯誤的原因
• 如何解決錯誤

事實上，能做到這一點的文檔就會少很多了，GitHub 的 API 文檔在這方面做的比較一般，Context.IO 的文檔 在錯誤信息上表現比較好，可以作為一個參考。

與全局內容相關的主題

這裡指的是對任何 API 文檔都通用且必需的內容，包括：

• 快速入門指南和教程
• 許可權認證相關信息
• HTTP 請求方式和錯誤處理

至於這些部分的內容會根據不同的後端服務而有差異，同時，在每個具體的 API 解釋中，出現與這些內容相關的概念時，可以給出具體章節的鏈接，便於開發者隨時跳轉查看。

一些可用性建議

API 文檔可以提供一些小功能來提升用戶的體驗。例如在代碼示例旁設置複製代碼的按鈕，方便用戶一鍵複製代碼；為調用 API 的代碼示例提供多語言支持，用戶可以查看不同語言調用 API 的示例，配合複製功能，可以減少書寫重複代碼的工作量。

API 文檔長什麼樣？

一個好的 API 文檔，除了內容合理詳細之外，它的樣式和交互方式也要簡單易用。現在的 API 文檔基本基於網頁來展現，利用網頁的顯示特性，有一些比較常見的設計方式。在這裡推薦一些適合作為 API 文檔展現要素的一些最佳實踐。

• 單頁形式

只要 API 文檔不是特別龐大，都推薦用單頁形式展現，在單個頁面中查找任何內容（無論是用瀏覽器的網頁搜索還是用文檔提供的導航），速度都會很快，再加上設置在頁面中的錨點，分享某條 API 記錄的位置也很方便。當然，如果 API 文檔內容過多，強行放在單頁面中會影響頁面體驗，就應該果斷對文檔進行拆分，但要記得在每個子頁面中保留全局的導航信息，方便用戶在各個頁面進行跳轉。

• 固定導航欄

使用 API 文檔的過程中，由於需要頻繁查找內容，固定在頁面中的導航欄顯得十分必要，用戶可以隨時通過導航欄查找文檔的內容。

• 多列布局

既然用了固定位置的導航欄，同時使用多列布局的形式也很順理成章。在寬屏的桌面端網頁上，多列布局可以很好的組織文檔的內容，導航、API 說明、代碼示例可以各佔一列。

API 文檔的維護

維護 API 文檔應該像維護一個獨立項目一樣，每次更新都通過拉取分支的形式，編輯者在檢查了文檔內容的正確性和簡潔性後，由項目成員進行 review。

在 API 文檔發布後，後期維護同樣重要。主要有兩個方面的內容：

1. 新功能和廢棄功能。在發布新功能之前應先發布文檔，並保證文檔經過了標準的 review 流程。對於廢棄掉的舊功能，應從文檔中移除，同時建議在相應的位置給出廢棄功能的提示和升級指南，方便使用舊功能的開發者進行升級工作。
2. 在文檔頁面上應該預留文檔的 contribute 入口，如果文檔託管在 GitHub 這樣的平台上就提供指向倉庫的鏈接，方便每個閱讀文檔的用戶給文檔提 Issue 或者 PR。如果文檔是閉源的，也應該至少留有提供反饋信息的位置。

以上是對項目開發合作中寫出友好的 API 文檔的一些想法和建議，歡迎討論。