首页 > 代码库 > 附录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:接口文档参考模板
声明:以上内容来自用户投稿及互联网公开渠道收集整理发布,本网站不拥有所有权,未作人工编辑处理,也不承担相关法律责任,若内容有误或涉及侵权可进行投诉: 投诉/举报 工作人员会在5个工作日内联系你,一经查实,本站将立刻删除涉嫌侵权内容。