前言
每个项目进行研发之前,都会有很多的相对应的文档,当然比较重要的一个就是接口文档,当然接口文档版本也有很多,这边只是把自己写文档的一部分内容写个示例记录一下,方便以后自己查看。当然大家有很好的建议和意见可以关注和留言交流。
设置描述
设计描述,主要是介绍项目接口文档的业务及主要功能介绍,有交互方式、JSON数据交互格式、命名规则等做细分讲解。
1)接口的调用方式:
移动端通过WebService和其他通用的请求方式,调用服务器接口,返回JSON数据。
2)JSON的结构: 请求失败示例
{
"status":"0",
"message":"您尚未登录,请登录后继续操作"
}
请求成功示例
{
"status":"1",
"message":"",
"data":{
"userId":"565562",
"userName":"huangxianfeng",
"workList":[
{
"workId":"245632",
"workName":"完成登陆功能的实现"
},
{
"workId":"956412",
"workName":"完成编码的格式转换"
}
]
}
}
字段解析
status:1成功、0失败
message:错误日志,接口访问错误的时候返回的错误提示文字,访问成功 的时候为空 字符串
data:服务器返回的业务数据
3)约定
1.JSON数据中的所有元素标签均以小写字母开头,并遵循驼峰命名法命名
2.JSON的编码格式需为UTF-8的编码格式
3.传入参数必须要加入tranCode交易码(此参数为必须)
4.请求的参数名称也是要小写字母开头(驼峰命名法命名)
4)具体接口文档编写示例‘
以上就是所有接口文档的笔记,如若大家有什么好的建议和意见,可以留言或关注交流。
来源:oschina
链接:https://my.oschina.net/u/2547914/blog/813773