附錄1：接口文檔參考模板

原文鏈接：https://www.w3cschool.cn/phalapi/5fhi1tth.html

 

 

雖然提供了在線接口參數的查看，但在和客戶端對接過程中，我們作為后台開發，還是需要人工提供接口文檔給客戶端的，這里提供一個接口文檔編寫的模板，以供參考，並且以我們熟悉的?service=User.GetBaseInfo為例說明如何編寫高效的文檔。

溫馨提示：斜體字表示是注釋說明。

功能說明

對接口功能的簡單說明。
獲取用戶的基本信息。

接口URL

請求的相對鏈接和當前接口級參數，通常為?service=XXX.XXX + 公共接口參數。
/demo/?service=User.GetBaseInfo

參數說明

對當前接口級參數的說明，建議使用在線接口參數查詢工具，但以下的參數說明也是需要的。

參數	名字	是否必須	說明	示例
userId	用戶ID	是	表示用戶的ID	&user_iduser_id=1

返回參數

對當前接口級返回參數的說明，即對{"ret":返回狀態碼,"data":"應該業務數據","msg":"錯誤提示"}中的data部分進行說明。

{
    "ret": 200, "data": { "code": 0, //code=0表示正確獲取用戶信息，code=1時表示用戶不存在 "msg": "", //業務提示文案 "info": { //僅當code=0的情況下非空且有用戶信息 "id": "1", //用戶ID "name": "dogstar", //用戶名 "note": "oschina" //用戶來源 } }, "msg": "" }

示例

至少應包括成功示例，失敗示例可選

成功示例

請求：

http://phalapi.oschina.mopaas.com/Public/demo/?service=User.GetBaseInfo&user_iduser_id=1

返回：

{
    "ret": 200, "data": { "code": 0, "msg": "", "info": { "id": "1", "name": "dogstar", "note": "oschina" } }, "msg": "" }

---