日常項(xiàng)目開(kāi)發(fā)的過(guò)程中，接口文檔是必不可少的铺根。后端工程師與前端工程師之間需要接口文檔來(lái)定義數(shù)據(jù)傳輸協(xié)議位迂、系統(tǒng)對(duì)外暴露接口需要文檔來(lái)說(shuō)明、系統(tǒng)之間相互調(diào)用需要文檔來(lái)記錄接口協(xié)議等等掂林。對(duì)于一個(gè)完整的項(xiàng)目，接口文檔是至關(guān)重要的泻帮。那我們?nèi)绾螌?xiě)好一份接口文檔呢锣杂？今天就讓我們說(shuō)一說(shuō)接口文檔幾個(gè)重要的要素。
api
1赖阻、接口概述
接口概述主要說(shuō)明本接口文檔涉及到的業(yè)務(wù)功能點(diǎn)踱蠢，面向的閱讀對(duì)象以及接口文檔主要包括哪些業(yè)務(wù)的接口朽基，可以讓讀者有一個(gè)直觀的認(rèn)識(shí)。如：本文檔定義了中臺(tái)系統(tǒng)面向外部接入方的數(shù)據(jù)協(xié)議接口稼虎，主要包括：用戶注冊(cè)接口霎俩、同步用戶沉眶、授權(quán)認(rèn)證等接口杉适。適合閱讀的對(duì)象為接入中臺(tái)開(kāi)發(fā)者或者外部合作方…。這樣的一段描述片习，對(duì)于閱讀者來(lái)說(shuō)可以對(duì)整個(gè)接口文檔有一個(gè)大概的認(rèn)識(shí)蹬叭。
接口概述
2秽五、權(quán)限說(shuō)明
有的接口調(diào)用需要授權(quán)認(rèn)證，在這部分需要進(jìn)行說(shuō)明盲再。如果接口只是基于分配的token認(rèn)證瓣铣，那文檔需要說(shuō)明token的獲取方式。如果接口需要進(jìn)行簽名認(rèn)證绿映，需要在這里說(shuō)明簽名的具體方法腐晾，如下圖：
api權(quán)限說(shuō)明
sign參數(shù)的生成規(guī)則要具體說(shuō)明藻糖，最好能示例說(shuō)明库车，如：
簽名方式
這樣接入方可以驗(yàn)證自己的簽名方式是否正確柠衍。
3、編碼方式
接口的請(qǐng)求過(guò)程中可能由于編碼導(dǎo)致亂碼珍坊，所以阵漏，接口必須約定編碼方式翻具，參考以下寫(xiě)法：
編碼方式
4裆泳、請(qǐng)求說(shuō)明
接口文檔的請(qǐng)求說(shuō)明中主要說(shuō)明接口請(qǐng)求的域名以及請(qǐng)求的數(shù)據(jù)格式：如
請(qǐng)求說(shuō)明
5柠硕、接口列表
接口列表是接口文檔的主要內(nèi)容蝗柔，這部分內(nèi)容需要列出所有的接口名稱、接口地址诫咱、接口的請(qǐng)求方式、接口的請(qǐng)求參數(shù)以及響應(yīng)格式竟痰。在接口的請(qǐng)求參數(shù)中我們需要說(shuō)明每個(gè)參數(shù)的含義掏呼、類型以及是否必須等屬性憎夷。對(duì)于接口響應(yīng)結(jié)果，如果有業(yè)務(wù)字段祥得，也需要進(jìn)行說(shuō)明蒋得。下面是一個(gè)比較完整的示例：
接口示例
6、狀態(tài)碼說(shuō)明
接口的響應(yīng)體一般都會(huì)帶有響應(yīng)的狀態(tài)碼额衙，例如成功、失敗等县踢。狀態(tài)碼有助于接入方進(jìn)行接口調(diào)用狀態(tài)的判斷伟件。如：
狀態(tài)碼
接口文檔如果能體現(xiàn)出以上幾個(gè)要素锋爪，那可以算是一個(gè)完整的接口文檔爸业，對(duì)于接入方來(lái)說(shuō)可以很好的閱讀理解扯旷。
作者:阿邁達(dá)聊技術(shù)
來(lái)源：https://www.toutiao.com/a6750576077665468931/?channel=&source=search_tab
