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

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

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

功能說明

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

接口URL

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

參數(shù)說明

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

返回參數(shù)

對當(dāng)前接口級返回參數(shù)的說明，即對{"ret":返回狀態(tài)碼,"data":"應(yīng)該業(yè)務(wù)數(shù)據(jù)","msg":"錯誤提示"}中的data部分進行說明。

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

示例

至少應(yīng)包括成功示例，失敗示例可選

成功示例

請求：

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