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