首页 > 代码库 > 附录1:接口文档参考模板

附录1:接口文档参考模板

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

 

附录1:接口文档参考模板

由 chanzonghuang 创建,最后一次修改 2016-11-20

虽然提供了在线接口参数的查看,但在和客户端对接过程中,我们作为后台开发,还是需要人工提供接口文档给客户端的,这里提供一个接口文档编写的模板,以供参考,并且以我们熟悉的?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": ""
}

附录1:接口文档参考模板