https://www.w3cschool.cn/phalapi/5fhi1tth.html

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

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

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

功能說明

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

接口URL

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

參數說明

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

返回參數

對當前接口級返回參數的說明，即對{"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": ""
}
 

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