接口文档标准规范.docx

接口文档标准规范.docx

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

接口文档标准规范

XXX接口阐明书

（版本：

V1.0）

文档编号

保密等级

作者

最后修改日期

审核人

最后审批日期

批准人

最后批准日期

修订记录

日期

版本

修订阐明

修订人

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：

'-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：

''

}