一、什么是接口文檔？

在項目開發(fā)中，web項目的前后端分離開發(fā)，APP開發(fā)，需要由前后端工程師共同定義接口，編寫接口文檔，之后大家都根據(jù)這個接口文檔進行開發(fā)，到項目結(jié)束前都要一直維護。

二、為什么要寫接口文檔？

1. 項目開發(fā)過程中前后端工程師有一個統(tǒng)一的文件進行溝通交流開發(fā)
2. 項目維護中或者項目人員更迭，方便后期人員查看、維護

三、接口規(guī)范是什么？
首先接口分為四部分：請求方式、uri、請求參數(shù)、返回參數(shù)

1. 請求方式:新增(post) 修改(put) 刪除(delete) 獲取(get)
2. uri：以/a開頭，如果需要登錄才能調(diào)用的接口(如新增、修改；前臺的用戶個人信息，資金信息等)后面需要加/u，即：/a/u；中間一般放表名或者能表達這個接口的單詞；get方法，如果是后臺通過搜索查詢列表，那么以/search結(jié)尾，如果是前臺的查詢列表，以/list結(jié)尾；url參數(shù)就不說了。
3. 請求參數(shù)和返回參數(shù)，都分為5列：字段、說明、類型、備注、是否必填
   字段是類的屬性；說明是中文釋義；類型是屬性類型，只有String、Number、Object、Array四種類型；備注是一些解釋，或者可以寫一下例子，比如負(fù)責(zé)json結(jié)構(gòu)的情況，最好寫上例子，好讓前端能更好理解；是否必填是字段的是否必填。
4. 返回參數(shù)結(jié)構(gòu)有幾種情況：1、如果只返回接口調(diào)用成功還是失?。ㄈ缧略?、刪除、修改等），則只有一個結(jié)構(gòu)體：code和message兩個參數(shù)；2、如果要返回某些參數(shù)，則有兩個結(jié)構(gòu)體：1是code/mesage/data，2是data里寫返回的參數(shù),data是object類型；3、如果要返回列表，那么有三個結(jié)構(gòu)體，1是code/mesage/data,data是object，里面放置page/size/total/totalPage/list 5個參數(shù)，其中l(wèi)ist是Arrary類型，list里放object，object里是具體的參數(shù)。

• 注意：uri地址里不允許出現(xiàn)大寫字母，如果是兩個單詞拼接，用/分開

• 鏈接

四.接口文檔實例

image

image