正規的團隊合作或者是項目對接,接口文檔是非常重要的,一般接口文檔都是通過開發人員寫的。一個工整的文檔顯得是非重要。下面我總結下自己看到的優秀接口文檔。
一、背景介紹
接口:API
API(Application Programming Interface)即應用程序接口。可以認爲 API 是一個軟件組件或是一個 Web 服務與外界進行的交互的接口。
目的是提供應用程序與開發人員基於某軟件或硬件得以訪問一組例程的能力,而又無需訪問源碼,或理解內部工作機制的細節。
從另一個角度來說,API是一套協議,規定了我們與外界的溝通方式:如何發送請求和接收響應。
我對API的理解
API就是把某些功能封裝好,方便其他人調用。調用的人只要滿足接口暴露給調用者的一些訪問規則就能很方便使用這些功能,並且可以不需要知道這些功能的具體實現過程。
什麼是接口文檔?
在實際項目開發中,web項目是前後端分離開發的,APP開發,需要由前後端工程師共同定義接口,編寫接口文檔,之後大家都根據這個接口文檔進行開發,到項目結束前都要一直維護。
二、知識剖析
接口分爲四部分:
1、方法:新增(post) 修改(put) 刪除(delete) 獲取(get)
2、uri:以/a開頭,如果需要登錄才能調用的接口(如新增、修改;前臺的用戶個人信息,資金信息等)後面需要加/u,
即:/a/u;中間一般放表名或者能表達這個接口的單詞;get方法,如果是後臺通過搜索查詢列表,那麼以/search結尾,
如果是前臺的查詢列表,以/list結尾。
3、請求參數和返回參數,都分爲5列:字段、說明、類型、備註、是否必填
字段是類的屬性;說明是中文釋義;類型是屬性類型,只有String、Number、Object、Array四種類型;備註是一些解釋,或者可以寫一下例子,
比如負責json結構的情況,最好寫上例子,好讓前端能更好理解;是否必填是字段的是否必填。
4、返回參數結構有幾種情況:1、如果只返回接口調用成功還是失敗(如新增、刪除、修改等),則只有一個結構體:
code和message兩個參數;2、如果要返回某些參數,則有兩個結構體:1是code/mesage/data,2是data裏寫返回的參數,data是object類型;
三、接口文檔生成工具
國產接口測試和接口文檔生成工具apipost,既可以在你開發完接口之後對接口進行測試
還能夠前後端實現接口聯調,接口開發完善之後還可以生成各種格式的接口文檔
分享接口,可以通過分享的接口鏈接,查看在線的接口文檔
還可以下載其他格式的接口文檔
如word格式的接口文檔