譯者 | 陳峻
審校 | 重樓
不知您是否注意到，編寫應用程序接口（API）文檔是每個開發人員的一項重要基本技能。想象一下，用戶拿到了一款好評如潮的新設備，卻看不懂配套的說明書，他該如何有效地去使用呢？API也是同理：如果沒有適當的文檔作為指南，提供如何使用其服務的基本信息，那么使用它的開發人員就可能不知所措。因此，就像一本精心編寫的設備說明書一樣，優秀的API文檔應當包括：代碼示例、教程以及有關函數、類和返回類型等詳細信息。作為一種全面的資源，它將能夠為開發人員提供無縫集成和有效調用的所需信息。
在本文中，我們將以創建出色的API文檔為目標，指導您使用簡單的語言，提供實用的示例，以確保開發人員能夠輕松理解和應用這些信息，進而簡化他們的集成過程。
什么是API文檔？
API是應用程序編程接口（Application Programming Interface）的縮寫，是不同軟件應用程序之間相互通信的橋梁。其文檔提供了與特定API集成和協作的重要指南。從根本上說，API文檔是一套指導開發人員和其他利益相關者利用應用程序接口、及其服務，進行無縫交互，實現特定目標的指南。它就像一本全面的手冊，為如何有效地與API進行交互，利用其功能，實現預期結果等，提供了清晰的指導。
此類文檔提供了包括：請求結構、預期響應、錯誤消息處理、以及其他基本功能等各方面的詳細信息。因此，它為開發人員提供了成功將應用程序接口納入其項目，并充分利用其功能，所需要獲悉的知識和指導。
簡單地說，API使得開發人員能夠全面利用成熟的平臺功能，而無需重新“發明輪子”。例如，Twitter和GitHub等主要平臺都提供了各自的應用程序接口，以便開發人員將其所需的功能，無縫地整合到自己的應用程序中。這不僅節省了他們的時間和精力，還促進了開發社區內的協作和創新，畢竟開發人員可以更加專注于構建應用程序的獨特方面，而不必從頭開始創建某些通用功能。
API文檔的類型
1.內部應用程序接口（面向團隊）
內部API專為在公司內部網絡中的使用場景而設計。它有效地促進了不同團隊和系統之間高效的數據交換，也簡化了組織內部的溝通。注意，在該場景下，內部開發人員是主要用戶，需要實現無縫的協作和信息流的交互。
2. 合作伙伴應用程序接口（針對合作伙伴）
合作伙伴API將訪問權限擴展到了組織之外，不過僅與那些可信賴的業務合作伙伴共享。這些應用程序接口會通過更高的安全措施，來限制授權客戶的訪問。在該場景下，其重點是保持安全的業務關系，并實現對特定功能的受控式外部訪問。
3.終端用戶應用程序接口（面向終端用戶）
最終用戶API也稱為開放式API，即：沒有嚴格的限制，任何開發人員都可以訪問到。這種API文檔的主要目的是鼓勵廣泛的采用，因此其認證和授權措施通常較為寬松。這也是為什么此類API的提供者通常會以廣泛的開發者參與為目標，有時甚至會根據API的調用量，提供分級訂閱式的訪問收費標準。這種在開發和使用上的開放性和靈活性，也是持續支持其營收的一種策略。
誰來編寫API文檔？
作為應用程序接口的設計者，開發人員會發現自己經常需要扮演記錄其創造成果的角色。畢竟他們對于自己開發的API所涉及到的錯綜復雜的技術知識，最為了如指掌。然而，潛在的缺點也隨之出現了，正是因為這種密切的聯系，往往會導致技術文檔過于專業，可能缺乏以更為友好的方法，讓廣泛的用戶對其理解和使用。此外，將主要精力放在開發和維護API上，有時也會導致文檔的優先級被放置到了次要位置。
因此，許多公司選擇了另一種方法，來應對該挑戰，即：讓專業技術撰寫人員參與到文檔編制的過程中。這些人員擁有將技術理解與創新能力相結合的技能。他們的職責是在API的技術方面，為后續將使用該接口的開發人員，量身定制出清晰的內容“圖譜”。
當然，這離不開上述兩種角色的密切合作。也就是說，應用程序接口開發人員需要通過向技術撰寫人員提供準確的、接口所需的信息記錄，并按需澄清某些細節上的缺失，以確保合作所產生的文檔具有全面性和連貫性。最終，這份精心制作的文檔會在技術深度和易讀性之間取得平衡，為目標受眾提供清晰且有價值的資源。
API文檔應包括哪些內容
1.概述
API文檔的基礎部分通常稱為概述。作為對API的簡要介紹，它總結了應用程序接口的目的，概述了其獨特的“賣點”。同時，它也可以強調該API在選用上的優勢，以及能夠為潛在用戶提供哪些有價值的見解。例如，在天氣類API的文檔中，其概述需要簡明扼要地指出：“本API可以提供全球各地的實時天氣數據，可準確地預報或提供歷史氣候信息。”
2.教程
作為文檔的核心部分，教程在向用戶介紹API的概念、以及實際用法方面，發揮著核心作用。其包含的循序漸進的指南，旨在幫助用戶清楚地了解具體的集成過程，并展示適當的功能和使用場景。
3.認證
身份驗證詳細說明了API提供方如何確保開發人員和最終用戶的數據安全。鑒于可能存在多種身份驗證方法，文檔應闡明其中的每一種方法，以便用戶全面了解如何安全地訪問該API。例如，在社交媒體類API的文檔中，身份驗證細節可以向開發人員解釋如何安全地獲取訪問其令牌。例如：“要訪問用戶數據，開發人員必須通過注冊應用程序，并按照既定的身份驗證流程獲取OAuth 2.0訪問令牌。”
4.端點定義
API的端點定義，可以精確地定位應用程序接口與軟件程序連接的位置。在描述這個被稱為端點的交互點時，文檔會包含服務器的URL或者是服務等詳細信息，從而明確API與其他系統的接口方式。例如：對于消息類API而言，文檔會將端點指定為“https://api.messaging.com”，以說明服務器的位置，進而方便開發人員與消息服務進行交互。
5.狀態和錯誤代碼
狀態和錯誤代碼對于開發人員了解API是否能夠按照預期運行，是至關重要的。它包括了對于不同狀態或錯誤情形的描述，以及開發人員該如何查找和解決遇到的問題的相關說明。例如，在文件存儲類API的文檔中，狀態和錯誤代碼可能包括：成功上傳文件的“200 OK”、以及試圖訪問不存在文件的“404 Not Found”。通常，每段代碼都會附有相應的說明和解決方法。
6.舉例說明
一旦用戶掌握了API的內部工作原理，提供示例就顯得水到渠成了。示例能夠展示成功的API調用、響應、錯誤處理程序和其他常見操作。這種實用的示例可以增強用戶對API的理解，并幫助用戶有效地應用API。例如，針對以構造地圖類API為基礎的應用，示例可以將成功調用展示為“GET /maps/location?lat=37.7749&long=-122.4194”，并返回詳細的位置數據。而錯誤示例則可以展示失敗的驗證嘗試，并指導開發人員該如何正確地處理錯誤。
7.術語表
術語表可以通過提供技術術語、模式和其他專業術語的簡明定義，來簡化開發者對于文檔的理解。這種方法既能夠確保文檔的清晰度，又不會給用戶帶來不必要的復雜技術問題。例如，在機器學習類API的文檔中，“模型訓練”等術語需要被鏈接到術語表的相應位置，進而提供簡明的解釋--“模型訓練是使用標注數據指導算法，以提高其預測準確性的過程。”
編寫優秀的API文檔的實踐
1.了解您的受眾
了解受眾是創建有效API文檔的基礎。我們應盡量避免假定受眾具有統一的專業知識水平，而需要充分考慮到初學者和經驗豐富的開發人員，在背景和技能水平上的差異，進而通過文檔定制化，來滿足他們的特定需求，真正為其所用。例如，對于初學開發者而言，請提供清晰的解釋和代碼示例，并盡量使用“讀取數據”之類直白的語言，而不是“執行GET請求”這樣的專業術語。
2.撰寫好介紹
作為給開發人員的“見面禮”，下面我們來討論如何將API文檔的介紹部分寫得內容豐滿。
- 明確說明目的在本節中，請說明API的主要用途，以便開發人員通過集成您的API實現其開發目標。因此，請確保陳述簡潔明了，避免模棱兩可。
- 設定預期概述開發人員能夠從該文檔獲取的內容。即，文檔是否包括：詳細指南、用例、故障排除技巧，以及針對不同開發人員的特定部分。設定好明確的預期，將有助于用戶有目的地瀏覽和使用文檔。
- 避免使用過于專業的術語
如前所述，介紹部分是開發人員與該API的第一次互動，因此要力求清晰易懂，給受眾留下積極的初始體驗。
下面，讓我們來看某個API的介紹示例：
## 介紹范例
歡迎訪問XYZ的API文檔！無論您是經驗豐富的開發人員，還是剛剛開始編碼之旅的新手，本文檔都可以成為您了解和使用XYZ API強大功能的入口。
**XYZ API的目的：**
XYZ API被設計為[此處可明確說明主要目的或功能]。它旨在[此處可說明能夠解決的特定問題或提供哪些服務]。
**使用本文檔的預期：**
在本文檔中，您將能找到全面的指南、示例和參考資料，可幫助您將XYZ API集成到自己的項目中。無論您是在查找[此處可填特定用例]，還是在[此處可填常見問題]方面需要幫助，本文檔都能為您提供線索。
**誰需要閱讀本文檔：**
本文檔適合[此處可填目標受眾]。無論您是前端開發員、數據科學家、還是API愛好者，您都能夠在此找到有價值的信息，以增強XYZ API的使用體驗。
3.提供代碼樣本
開發人員通常會依靠各種示例，來了解如何有效地與API進行交互。因此，在展示代碼片段時，我們應確保其簡明扼要、注釋清晰。這將有助于用戶，尤其是那些對技術不太熟悉的用戶，更容易地掌握API的功能。下面是一個Python示例：
# Python 示例
Python
import requests
url = "https://api.weathernow.com/current"
response = requests.get(URL)
data = response.json()
print("Current temperature:", data['temperature'])4.使用一致的命名規則
命名規則的一致性可以提高文檔的可讀性。通過對端點、參數和響應采用清晰統一的術語，可以避免不必要的混淆，畢竟不一致性往往會導致誤解和錯誤的產生。此外，保持標準化的命名方法，可以為開發人員創造更順暢的學習體驗，使他們能夠更容易地將您的API集成到自己的項目中。例如：請不要交替使用“temp”、“temperature”、以及“temp_data”，而需要在整個文檔中統一為“temperature”的術語。
5.包括請求和響應示例
開發人員需要根據有關預期輸入參數和API響應結構的相關記錄，來了解應如何格式化請求，并解析API返回的數據。因此，我們需要為請求和響應提供現實的示例，以彌合理論解釋和實際執行之間的差距，讓開發人員無障礙地使用您的API。下面是一個典型的請求示例代碼：
// 請求示例
JSON
{
"city": "New York",
"units": "metric"
}
// Response Example
{
"Temperature": 23,
"condition": "Clear",
"humidity": 50
}6.錯誤處理信息
由于清晰的錯誤處理信息更利于排障，因此我們需要在文檔中體現潛在的錯誤代碼、信息及其含義，以確保能夠指導開發人員該如何處理這些錯誤。這種積極主動的方式，不僅能夠幫助開發人員迅速解決問題，還可以減少他們的挫敗感與困惑，進而帶來積極的用戶體驗。例如：一旦發現被提交的請求中沒有需要必填的參數，API則應給出諸如“缺少必填參數：城市”等明確的錯誤信息。
7.添加限速信息
文檔中應體現與API相關的任何速率限制信息，以協助開發人員有效管理API的使用情況，進而避免因速率限制問題而造成的服務中斷。此外，文檔還應包含檢查API的當前使用情況和處理限速的錯誤詳細信息，以幫助開發人員優化應用本身的性能，并確保其能夠與該API進行更順暢的集成。例如：“我們的API速率限制為：每小時100個請求。如果超過此限制，您將收到‘429過多請求’的狀態代碼。若要檢查您的使用情況，請在響應中包含‘X-Rate-Limit-Remaining’標頭”。
8.保持更新
定期更新文檔可以方便開發人員了解API的相關變更、新增功能、以及廢棄了的功能。因此，通過文檔來傳遞版本信息、維護更新日志、以及突出修改的內容，都將有助于在用戶群中培養一種針對API可靠性的信任感，特別是在您能夠主動更新文檔的情況下。例如，在發布說明中，您可以提及：“2.0版引入了新的端點‘/forecast’，可用于擴展天氣預測”。
9.鼓勵反饋
文檔中應鼓勵開發人員分享經驗、提出問題與建議。這種雙向交流將有助于您及時解決潛在的問題，更好地了解用戶需求，從而不斷改進API的功能及其文檔。例如：“我們非常重視您的反饋意見！如果您有任何疑問、建議或遇到任何問題，請聯系我們的支持團隊：support@xyz.com”。
10.避免含糊不清和假設
清楚地闡明您的指令，避免對用戶已有的知識做出假設。請記住，模棱兩可或含糊不清的文檔只會導致誤解和實施錯誤。只有清晰的解釋，才能確保那些經驗有限的開發人員，也能自信地遵循您的文檔。例如，請不要簡單地使用一句“只需請求我們的API即可”，而需詳細地說明：“請向‘https://api.weathernow.com/current’發送HTTP GET請求，以檢索當前的天氣信息。”
11.不要過多地使用技術術語
專業術語雖然表達準確，但是也會妨礙用戶的理解。為了在準確性和易讀性之間取得平衡，最好的一種辦法是：在必要時，對技術術語進行定義和解釋，讓開發人員在理解文檔時不會產生歧義或是感到突兀。例如：將“利用異步通信范式提高可擴展性”的措辭改為“允許同時處理多個請求，進而提高性能”。
12.避免長篇大論
密集冗長的段落會讓人缺乏繼續閱讀的耐性，進而導致重要細節被忽略。對此，請確保使用要點、列表、短句、以及標題等分段格式，來有效地組織內容，從而在提高文檔可讀性的基礎上，方便用戶在文檔中快速找到所需的信息。例如：
- 使用HTTPS進行安全通信。
- 在“授權”標頭中包含API密鑰。
- 在“接受”標頭中指定所需的輸出格式。
小結
綜上所述，有效編寫API文檔是一個多層次的過程。它既需要深入了解受眾，又需要提供清晰的介紹，實用的代碼示例、鼓勵用戶反饋，并致力于不斷的改進。相信通過遵循上述介紹的步驟和實踐，您也可以創建出讓開發人員倍感實用，并使其能夠與API無縫集成的優秀說明文檔。
譯者介紹
陳峻（Julian Chen），51CTO社區編輯，具有十多年的IT項目實施經驗，善于對內外部資源與風險實施管控，專注傳播網絡與信息安全知識與經驗。
原文標題：How to Write API Documentation: Best Practices and Examples，作者：Toluwani Folayan
