使用cursor生成接口文档

1.第一次提问
给的答案比较草率
2.第二次完善提问
这次答案就比较详细
总结:1.需要不断完善提问话术,让AI能够更清楚的了解你的需求
2.代码结构标准,方法注释,实体类注释都必须明确(入参,出参必须实体封装,这也是面向对象的思想,有些人为了省事喜欢用map封装,这样就AI就无法知道字段的含义,从而无法生成具体的内容)
PayController 接口文档
目录
1. 支付接口
接口地址:/pay/orderPay
请求方式:POST
接口描述:用于处理支付请求
请求参数
请求体(PayDTO)
{
"orderId": "ORDER123456", // 订单id,不能为空
"qrCode": "QRCODE12345", // 支付二维码,不能为空
"posNum": "POS123456", // pos机设备编码,不能为空
"amount": 100.50 // 支付金额,必须大于0
}
参数名 | 类型 | 是否必填 | 说明 |
---|---|---|---|
orderId | String | 是 | 订单id |
qrCode | String | 是 | 支付二维码 |
posNum | String | 是 | pos机设备编码 |
amount | BigDecimal | 是 | 支付金额(必须大于0) |
返回参数
{
"code": 200, // 状态码:200成功
"msg": "操作成功", // 返回信息
"data": {
// 支付相关的返回信息,具体内容根据实际业务返回
}
}
2. 退款接口
接口地址:/pay/refundOrder
请求方式:POST
接口描述:处理退款请求
请求参数
请求体(RefundOrderReqDTO)
{
"outTradeNo": "ORDER123456", // 订单号,不能为空
"outRefundNo": "REFUND123456", // 退款单号
"totalFee": 10000, // 订单金额(单位:分)
"refundFee": 10000, // 退款金额(单位:分)
"opUserId": "USER001", // 操作人
"matchData": "匹配数据" // 匹配字符串
}
参数名 | 类型 | 是否必填 | 说明 |
---|---|---|---|
outTradeNo | String | 是 | 订单号 |
outRefundNo | String | 否 | 退款单号 |
totalFee | Integer | 否 | 订单金额(单位:分) |
refundFee | Integer | 否 | 退款金额(单位:分) |
opUserId | String | 否 | 操作人 |
matchData | String | 否 | 匹配字符串 |
返回参数
{
"code": 200, // 状态码:200成功
"msg": "操作成功", // 返回信息
"data": null // 无返回数据
}
3. 支付订单轮询接口
接口地址:/pay/orderPoll
请求方式:GET
接口描述:轮询查询支付订单状态
请求参数
参数名 | 类型 | 是否必填 | 说明 |
---|---|---|---|
orderNum | String | 是 | 订单号 |
返回参数
{
"code": 200, // 状态码:200成功
"msg": "操作成功", // 返回信息
"data": {
"status": 1, // 状态:1-支付中,2-支付成功,3-支付失败
"printData": { // 仅支付成功时返回打印数据
"MerchantName": "内蒙古电力集团有限责任公司", // 商户名称
"MerchantNo": "123456", // 商户号
"posNum": "POS123456", // 终端编号
"payAmount": "100.50", // 交易金额
"payType": "微信支付", // 交易方式
"payTime": "2024-03-15 12:30:45", // 交易时间
"orderNum": "ORDER123456", // 商户订单号
"holderNum": "100001", // 户号
"holderName": "张三", // 户名
"address": "北京市海淀区中关村", // 地址
"etcType": "居民生活用电", // 用电类型
"totalRcvblAmt": "100.00", // 合计电费
"totalPenalty": "0.50", // 应收违约金
"totalAvailBal": "0.00", // 账户余额
"rcvblAmtSum": "100.50" // 应收合计
},
"orderNum": "ORDER123456" // 仅支付成功时返回订单号
}
}
4. 获取打印小票相关数据
接口地址:/pay/getReceiptInfo
请求方式:GET
接口描述:获取打印小票的相关数据
请求参数
参数名 | 类型 | 是否必填 | 说明 |
---|---|---|---|
orderNum | String | 是 | 订单号 |
返回参数
{
"code": 200, // 状态码:200成功
"msg": "操作成功", // 返回信息
"data": {
"MerchantName": "内蒙古电力集团有限责任公司", // 商户名称
"MerchantNo": "123456", // 商户号
"posNum": "POS123456", // 终端编号
"payAmount": "100.50", // 交易金额
"payType": "微信支付", // 交易方式
"payTime": "2024-03-15 12:30:45", // 交易时间
"orderNum": "ORDER123456", // 商户订单号
"holderNum": "100001", // 户号
"holderName": "张三", // 户名
"address": "北京市海淀区中关村", // 地址
"etcType": "居民生活用电", // 用电类型
"totalRcvblAmt": "100.00", // 合计电费
"totalPenalty": "0.50", // 应收违约金
"totalAvailBal": "0.00", // 账户余额
"rcvblAmtSum": "100.50" // 应收合计
}
}
5. 插入流水记录
接口地址:/pay/insertFlow
请求方式:GET
接口描述:插入支付流水记录
请求参数
无
返回参数
{
"code": 200, // 状态码:200成功
"msg": "操作成功", // 返回信息
"data": null // 无返回数据
}
6. 发送支付资金流水
接口地址:/pay/sendPayCapitalFlow
请求方式:GET
接口描述:发送支付资金流水
请求参数
无
返回参数
{
"code": 200, // 状态码:200成功
"msg": "操作成功", // 返回信息
"data": null // 无返回数据
}
7. 插入历史流水记录
接口地址:/pay/insertHistoryFlow
请求方式:GET
接口描述:插入历史流水记录
请求参数
参数名 | 类型 | 是否必填 | 说明 |
---|---|---|---|
startTime | String | 是 | 开始时间 |
endTime | String | 是 | 结束时间 |
返回参数
{
"code": 200, // 状态码:200成功
"msg": "操作成功", // 返回信息
"data": null // 无返回数据
}
8. 演示接口
接口地址:/pay/demo
请求方式:GET
接口描述:获取流水的演示接口
请求参数
无
返回参数
{
"code": 200, // 状态码:200成功
"msg": "操作成功", // 返回信息
"data": null // 无返回数据
}
数据结构说明
PayDTO - 支付请求对象
字段名 | 类型 | 是否必填 | 说明 |
---|---|---|---|
orderId | String | 是 | 订单id |
qrCode | String | 是 | 支付二维码 |
posNum | String | 是 | pos机设备编码 |
amount | BigDecimal | 是 | 支付金额(必须大于0) |
RefundOrderReqDTO - 退款请求对象
字段名 | 类型 | 是否必填 | 说明 |
---|---|---|---|
outTradeNo | String | 是 | 订单号 |
outRefundNo | String | 否 | 退款单号 |
totalFee | Integer | 否 | 订单金额(单位:分) |
refundFee | Integer | 否 | 退款金额(单位:分) |
opUserId | String | 否 | 操作人 |
matchData | String | 否 | 匹配字符串 |
ReceiptVO - 小票打印数据对象
字段名 | 类型 | 说明 |
---|---|---|
MerchantName | String | 商户名称,默认为"内蒙古电力集团有限责任公司" |
MerchantNo | String | 商户号 |
posNum | String | 终端编号 |
payAmount | String | 交易金额 |
payType | String | 交易方式 |
payTime | String | 交易时间 |
orderNum | String | 商户订单号 |
holderNum | String | 户号 |
holderName | String | 户名 |
address | String | 地址 |
etcType | String | 用电类型 |
totalRcvblAmt | String | 合计电费 |
totalPenalty | String | 应收违约金 |
totalAvailBal | String | 账户余额 |
rcvblAmtSum | String | 应收合计 |
错误码说明
错误码 | 说明 |
---|---|
200 | 操作成功 |
201 | 对象创建成功 |
202 | 请求已被接受 |
204 | 操作已执行成功,但没有返回数据 |
400 | 参数列表错误(缺少,格式不匹配) |
401 | 未授权 |
403 | 访问受限,授权过期 |
404 | 资源,服务未找到 |
405 | 不允许的http方法 |
409 | 资源冲突,或资源被锁 |
415 | 不支持的数据,媒体类型 |
500 | 系统内部错误 |
501 | 接口未实现 |
601 | 系统警告消息 |