接口文檔相關問題

1.什麼是接口文檔？

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

2.爲什麼需要寫接口文檔？

• 項目開發過程中前後端工程師有一個統一的文件進行溝通交流開發
• 項目維護中或者項目人員更迭，方便後期人員查看、維護

3.什麼情況下需要接口文檔？

• 遠程協作開發。遠程開發，這種情況下是需要的
• 面對面開發。開發節奏不一致，所以需要接口文檔
• 接手別人項目。剛進來不熟悉，所以需要接口文檔

4.接口文檔怎麼寫，規範是什麼？

首先接口分爲四部分：請求方法、請求地址、請求參數、返回參數

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

5.接口文檔的常用工具？

• 易文檔，石墨文檔，eolinker，Yapi等，當然記事本也是可以的，只是不方便編寫，共享等

6.什麼時候寫接口文檔？

• 我們的做法是：
  1.前後端先過需求，然後制定出需要哪些接口，制定接口規範
  2.服務端給出json報文，標明各個字段含義，並給出模擬api
  3.然後客戶端就可以開始先做功能，調用模擬api
  4.前後端開發大體完成，進入集成測試，期間接口會做加減法，但是變動不大

• 以上，是基於有個好的架構負責梳理業務流程，畢竟先給出接口文檔和模擬API的是對業務流程把握的考驗，開發期間，有問題應該主動溝通，或者是每天上班開個幾分鐘晨會，報一下進度，還有反饋可能覺得出現的情況。

7.一般接口文檔是誰來寫的？
在項目開發中，前後端是分離的，爲了前後端的連貫性，一般由前後端工程師共同定義接口，編寫接口文檔