接口测试的依据，往往不是需求文档，而是接口文档。

那么，接口文档的准确性便至关重要，本文推荐两种形式的接口文档，供大家参考。


接口文档不管以什么形式存在，需要包含的内容有：

  1. 接口名称
  2. 接口类型
  3. 输入参数

                           每个参数名；

                           每个参数类型；

                           每个参数业务含义；

                           每个是否可空；

                           每个字段长度（可选，一般需要提供，有严格要求的字段需特别注明）；

                           每个参数的单位（可选，金额类字段需注明）；

d. 输出结果

                            每个参数名；

                            每个参数类型；

                            每个参数业务含义；

                            每个是否可空；

                            每个参数的单位（可选，金额类字段需注明）；

                            返回状态的取值范围及其业务含义。


目前接口文档有两种存在形式，下面分别给出实例：

文档型：

接口名称

账户转账接口

接口类型:

AccountTransferService.transfer

请求参数

AccountTransferRequest

参数分类

参数字段

参数类型

字段长度

是否可空

单位

参数描述

公用参数

requestModule

String

3

N

系统统一编号，必须提供，构造函数的方式

requestTime

Date

N

请求日期

accountRequestNo

String

32

N

外部系统请求账务请求编号

extension

LinkedHashMap<String, String>

Y

扩展

accountServiceCode

String

20

N

账务服务编码

requestType

RequestType

3

N

固定传 APPLY

凭证参数

merchantId

String

50

Y

商户号

outTradeNo

String

50

Y

商户订单号

tradeNo

String

32

Y

交易流水号

originalTradeNo

String

32

Y

原交易号

tradeType

TradeTypeEnum

5

Y

交易类型

subTradeType

SubTradeTypeEnum

4

Y

交易子类型

payMethod

PayMethodEnum

3

Y

支付方式

payTool

PITypeEnum

4

Y

支付工具类型

tradeMoney

Money

N

分

交易金额,必填，如果没有，请保持和payMoney一致。

tradeDate

Date

Y

交易日期

tradeDesc

String

200

N

交易说明

paymentNo

String

32

Y

支付服务流水

payReqTime

Date

Y

支付发起时间

payTime

Date

Y

支付成功时间

amount

Money

N

分

支付金额

cardType

CardTypeEnum

2

Y

卡类型

channelType

ChannelTypeEnum

6

Y

通道类型，手工还是联机

fundChannelCode

String

32

Y

资金渠道编码

fundChannelName

String

32

Y

资金渠道名称

instMerchantId

String

32

Y

资金渠道商户号

instOrderNo

String

32

Y

资金渠道流水号

instInnerTradeNo

String

32

Y

资金渠道内部交易流水号

evidenceExt

String

1000

N

evidenceDesc

String

128

N

凭证摘要

接口特定参数

payerMemberId

String

N

付款方会员编号

payerAccountNo

String

N

付款方账户号

payeeMemberId

String

N

收款方会员编号

payeeAccountNo

String

N

收款方账户号

响应参数

PaymentResult

responseCode

String

N

返回码

responseDesc

String

N

返回消息描述

accountRequestNo

String

N

外部系统请求编号(支付基础服务号)

evidenceNo

String

N

记账凭证号

accountingDay

String

N

记账会计日


Java doc型：


接口文档markdown demo 接口文档格式_接口文档markdown demo