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