附錄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": "" }