接口文档规范.docx

接口文档规范.docx

《接口文档规范.docx》由会员分享，可在线阅读，更多相关《接口文档规范.docx（10页珍藏版）》请在冰点文库上搜索。

接口文档规范

接口文档规范

XXX接口说明书

（版本：

V）

文档编号

保密等级

作者

最后修改日期

审核人

最后审批日期

批准人

最后批准日期

修订记录

日期

版本

修订说明

修订人

1简介

1.1文档目的

接口文档是前端与后端交互密不可分的环节，接口的规范性会直接影响双方对接过程中的效率和质量。

本着快速高效开发的目的性，避免对接过程中的错误率。

1.2接口规范

（1）遵循RESTfulAPI设计风格

（2）数据格式采用json格式

（3）返回统一结构数据

例如：

结构：

data（数据）、errorCode（状态码）、msg（提示信息）

{

data:

{},//数据类型不一定为object类型

errorCode:

10001,

msg:

''

}

（4）枚举型参数应列举参数所有值及说明

例如：

gender：

性别（男：

1，女：

2）

userInfo:

{

name:

'张三',

age:

23,

gender:

1

}

（5）具有嵌套关系的参数应指明嵌套关系及子级数据结构

例如：

billList:

账单列表（父级）

billList:

[

{

id:

'001',

billName:

'测试数据',

billStauts:

1,

address:

'雁塔区'

}

]

（6）返回参数数据类型保持一致性

例如：

billList:

账单列表（有数据）

billList:

[

{

id:

'001',

billName:

'测试数据',

billStauts:

1,

address:

'雁塔区'

}

]

billList:

账单列表（无数据）

billList:

[]

返回的参数数据类型都为：

array

（7）下拉及选择型数据以键值对的形式返回

例如：

orderOperate：

订单操作

orderOperate:

[

{

label:

'待开票'

value:

1001

},

{

label:

'回款'

value:

1003

}

]

（8）“操作类型”的接口必须返回msg信息内容

（9）返回的展示型数据应具有可用性

例如：

createTime：

生成时间（建议格式）

{

createTime:

'2018-8-2017:

00:

00'

}

建议：

由于前台处理数据能力较弱，故后台返回的数据尽可能便于前台使用。

2接口定义

2.1特殊接口

2.1.1获取服务器sessionKey

接口标识：

接口地址：

请求方式：

POST

请求参数：

参数名

类型

必填

示例值

默认值

描述

appType

number

是

1

1

1:

e站,2:

客户

code

string

否

wx.login返回的code

输出参数：

参数名

类型

示例值

默认值

描述

errorCode

number

100

100:

成功,-99:

失败,-10:

需要登录-20:

Session失效

msg

string

接口返回的文字消息

data

string

Api接口返回session值

返回示例值:

{

data:

'123456',

errorCode:

100,

msg:

''

}

2.2通用接口

2.2.1账单列表

接口标识：

接口地址：

请求方式：

POST

请求参数：

参数名

类型

必填

示例值

默认值

描述

id

number

是

订单id

sort

string

否

排序

gender

number

是

1

1

性别（男：

1，女：

2）

orderList

array

否

[...]

订单列表

orderList

orderId

string

否

订单id

orderName

string

否

订单名称

isStudent

boolean

是

false

false

是否学生（是：

true，否：

false）

返回参数：

参数名

类型

示例值

默认值

描述

data

array

[…]

返回的数据

data

id

string

用户id

gender

number

1

1

用户性别（男：

1，女：

2）

invoiceTitle

string

抬头

address

string

地址

billList

array

[...]

订单列表数据

billList

id

string

订单id

billName

string

订单名称

billStauts

number

1

1

订单状态（待开票：

1，回款：

2，核销：

3）

address

string

客户地址

userInfo

object

{}

用户信息

userInfo

name

name

用户姓名

age

number

用户年龄

gender

string

1

1

用户性别（男：

1，女：

2）

errorCode

number

状态信息

msg

string

信息提示

返回示例值:

{

data:

[

{

id:

'1',

gender:

2,

invoiceTitle:

'帝国快运',

address:

'陕西省西安市雁塔区科技路24号',

billList:

[

{

id:

'001',

billName:

'测试数据',

billStauts:

1,

address:

'雁塔区'

},

{

id:

'002',

billName:

'测试数据02',

billStauts:

1,

address:

'高新区'

}

],

userInfo:

{

name:

'张三',

age:

23,

gender:

1

}

},

{

id:

'2',

gender:

1,

invoiceTitle:

'圆通快递',

address:

'陕西省西安市雁塔区科技路24号',

billList:

[

{

id:

'003',

billName:

'测试数据',

billStauts:

1,

address:

'雁塔区'

},

{

id:

'004',

billName:

'测试数据02',

billStauts:

2,

address:

'高新区'

}

],

userInfo:

{

name:

'张三',

age:

23,

gender:

1

}

}

],

errorCode:

10001,

msg:

''

}