Style and formatting rules for…

# 支付网关 REST API 文档规范整理指南

一、整体文档结构规范

• 统一模板：每个接口文档按固定顺序编写：接口名称 → 简要描述 → 请求方式与路径 → 鉴权说明 → 请求参数表 → 请求示例 → 响应参数表 → 响应示例 → 错误码 → 注意事项
• 版本标识：文档顶部标注 API 版本（如 /v1/），说明变更日志入口
• 基础信息前置：在文档开头统一说明 Base URL（区分测试/生产环境）、签名规则、幂等性要求等公共内容，避免每个接口重复

二、参数表格式规范

• 使用 Markdown 表格，列固定为：参数名 | 类型 | 是否必填 | 描述 | 示例值
• 金额类字段注明单位与精度要求（如分为单位的整数）
• 嵌套对象用层级缩进或父级参数名前缀（如 payer.user_id）表达

三、错误码说明规范（重点）

• 集中+局部结合：文档附录提供全局错误码总表，每个接口只列出与本接口强相关的业务错误码
• 错误码表建议列：错误码 | HTTP 状态码 | 错误信息 | 可能原因 | 处理建议
• 明确错误分类规则：
• 4xx：客户端错误（参数缺失、签名失败、余额不足等）
• 5xx：服务端错误，建议开发者重试策略
• 特别说明支付类错误码的幂等处理：如超时/未知状态错误，应提示用户通过查询接口确认结果，而非盲目重试

四、curl 示例代码规范（重点）

• 每个接口至少提供成功请求示例，写清完整的 curl 命令，包含：

```bash

curl -X POST https://api.example.com/v1/payments \

-H "Authorization: Bearer {access_token}" \

-H "Content-Type: application/json" \

-d '{"amount": 1000, "currency": "CNY", "order_no": "示例单号"}'

```

• 规范要点：
• 多行命令使用 \ 续行，参数对齐排版
• 请求头与请求体分开写，占位符用 {} 明确标注（如 {merchant_key}）
• 金额等敏感字段使用符合业务规则的示例值，不使用 0 或明显无意义值
• POST 接口必带 -H "Content-Type: application/json"
• 配套提供响应示例，成功与失败响应各一个，JSON 格式化缩进展示

五、执行建议

• 用统一风格校验脚本或 lint 工具（如 Markdown lint）批量检查 30 个接口格式一致性
• 抽取公共部分（鉴权、签名、通用错误码）为独立章节，减少冗余、便于维护