小皮博客 | Xiaopi's Blog

87-一个建议的接口文档模板

XXX电子商务平台API文档

======

基础说明

背景

[说明文档用途。]
编写本文的目的是为了将系统功能进行模块化、服务化,将用户的操作以服务的方式提供。系统与系统之间遵循服务规范,将系统与系统之间的交互转为定制化服务交互,以实现系统与系统之间的集成。

基本约束

基本设计原则

参考《86-RestAPI设计指南》

字符集

  • 所有接口字符集采用UTF-8。

返回类型约束

  • 所有接口返回必须是严格定义的JSON类型。

接口版本约束

  • 不允许发布无版本号的接口。
  • 接口版本首先解决的是一组接口的版本问题。

请求公共约束

请求的基本模板:

1
2
3
4
5
6
curl -X[HTTP METHOD] -H "Content-Type: application/json" -H "[token-info]:"   
"https://api-dev.[groupname].xiaoyuyu.io/[client-group]/[service-group-name]/
[version]/[endpoint]" -d '{
"head": [meta-parameters],
"body": [content]
}'

URL整体规划

域名规范

域名规划

接口认证

基本数据类型约定

此约定是系统整体容错的一部分,但是无论接口使用者还是接口生产者,都不应该因为此容错而减少自己模块本来需要的容错工作。

数据类型 类型说明 默认值 备注
JSONObject JSON对象 {}
JSONArray JSON数组 [] 数组中不允许使用混合类型
Integer 整型 Integer.MIN_VALUE
Float 浮点型 Float.MIN_VALUE
Char 字符型 空格
String 字符串 空字符串 不允许直接返回NULL
Boolean 布尔型 Boolean.FLASE 默认返回false
嵌套对象 嵌套对象 {} 根对象返回空,子对象不处理
嵌套数组 嵌套数组 [] 根对象返回空,子对象不处理

公共输入参数规范

TODO: 补充token,加密,国际化,等等

字段名 必须 数据类型 描述 示例
requestInfo JSONObject 表达每个请求的信息
requestInfo.sessionId String UUID,每次进入APP到退出算一次会话
requestInfo.reqId String UUID,每次请求独立生成一个Id
apkInfo JSONObject 表达每个apk的信息
apkInfo.apkType String 表示APK本身的类型 Dev,Debug,beta
apkInfo.apkId String UUID,每次安装会单独生成一个apkId
apkInfo.apkVersion String App的内部版本号
apkInfo.appVersion String App的显示版本号
clientInfo JSONObject 表达客户端的信息
clientInfo.ip String 客户端ipV4的地址
clientInfo.romInfo String 定制版操作系统的信息
clientInfo.deviceTag String 设备的标记
clientInfo.osInfo String 操作系统的信息
userInfo JSONObject 表达用户的信息
userInfo.userId String 用户的唯一标识符

公共返回对象约定

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
"responseCode": [responseCode],
"responseInfo": {
"userMessage": [userMessage],
"internalMessage": [internalMessage],
"guideline": [guideline link]
},
"link":
{
 "document":" https://[domain]/docs#zoos",
 "href":[uri-info],
 "title":[doc-title],
 "type":"application/[vnd.yourformat]+json"
},
"responseData":[responseData]
}

公共错误编码及说明

code 描述 适用范围 备注
20000 请求成功 全部 200表示成功,后两位00是补充编码

公共数据字典

字段名 取值 适用范围 备注
status 1,2,3 全部文档

订单服务

查询订单列表

接口规范























































































URL /{baseUri}/orders
HTTP Method GET
访问权限 基本验证,Https,用户验证
说明 查询某个用户的订单列表
请求参数
参数名称 必须 数据类型 描述 示范
body.pageSize YES Integer 一页的查询条目数 默认是10,最大值50
body.pageNo YES Integer 查询的页数 默认是1
body.sortBy NO String 参见数据字典,排序规则 默认按照时间倒排
body.from NO String 转换为Date,查询范围的开始时间 示范:2019-01-01 22:00:00
body.to NO String 转换为Date,查询范围的结束时间 示范:2019-01-01 22:00:00
返回参数
responseData.pageCount YES Integer 一共有多少页
responseData.pageNo YES Integer 当前的页数
responseData.data NO JSONObject 订单详细信息

输入参数示范

1
2
3
4
5
6
7
curl -XGET -H "Content-Type: application/json" -H "Access-Token:abcd1234" "https://api-dev.haitao.xiaoyuyu.io/mobile/data-platform/v1/orders/base-orders" -d '{
"head": [meta-parameters],
"body": {
"pageSize":10,
"pageNo":1
}
}'

返回参数示范


版权声明

本文标题:87-一个建议的接口文档模板

文章作者:盛领

发布时间:2019年01月14日 - 22:16:34

原始链接:http://blog.xiaoyuyu.net/post/abe8667.html

许可协议: 署名-非商业性使用-禁止演绎 4.0 国际 转载请保留原文链接及作者。

如您有任何商业合作或者授权方面的协商,请给我留言:sunsetxiao@126.com

盛领 wechat
欢迎您扫一扫上面的微信公众号,订阅我的博客!
坚持原创技术分享,您的支持将鼓励我继续创作!