一、什么是接口文檔?
在項目開發中,web項目的前后端分離開發,APP開發,需要由前后端工程師共同定義接口,編寫接口文檔,之后大家都根據這個接口文檔進行開發,到項目結束前都要一直維護。
二、為什么要寫接口文檔?
1、項目開發過程中前后端工程師有一個統一的文件進行溝通交流開發
2、項目維護中或者項目人員更迭,方便后期人員查看、維護
三、接口規范是什么?
首先接口分為四部分:方法、uri、請求參數、返回參數
1、方法:新增(post) 修改(put) 刪除(delete) 獲取(get)
2、uri:以/a開頭,如果需要登錄才能調用的接口(如新增、修改;前台的用戶個人信息,資金信息等)后面需要加/u,即:/a/u;中間一般放表名或者能表達這個接口的單詞;get方法,如果是后台通過搜索查詢列表,那么以/search結尾,如果是前台的查詢列表,以/list結尾;url參數就不說了。
3、請求參數和返回參數,都分為5列:字段、說明、類型、備注、是否必填
字段是類的屬性;說明是中文釋義;類型是屬性類型,只有String、Number、Object、Array四種類型;備注是一些解釋,或者可以寫一下例子,比如負責json結構的情況,最好寫上例子,好讓前端能更好理解;是否必填是字段的是否必填。
4、返回參數結構有幾種情況:1、如果只返回接口調用成功還是失敗(如新增、刪除、修改等),則只有一個結構體:code和message兩個參數;2、如果要返回某些參數,則有兩個結構體:1是code/mesage/data,2是data里寫返回的參數,data是object類型;3、如果要返回列表,那么有三個結構體,1是code/mesage/data,data是object,里面放置page/size/total/totalPage/list 5個參數,其中list是Arrary類型,list里放object,object里是具體的參數。
注意:uri地址里不允許出現大寫字母,如果是兩個單詞拼接,用/分開