文档规范

本文档定义了API文档的编写标准和规范。

文档结构标准

1. 基础信息区块

每个接口文档包含以下基础信息：

• 接口名称: 中文描述
• 请求方式: GET/POST/PUT/DELETE/PATCH
• 请求地址: 完整的API路径
• 接口描述: 简明的功能描述
• 认证要求: 是否需要token认证

2. 请求参数格式

路径参数

参数名	类型	必填	说明	示例
id	string	是	用户ID	"12345"

查询参数

参数名	类型	必填	说明	示例
pageNumber	number	否	页码，默认1	1
pageSize	number	否	每页数量，默认10	10

请求体参数

参数名	类型	必填	说明	示例
username	string	是	用户名	"john_doe"
email	string	是	邮箱地址	"user@example.com"

请求示例

{
  "username": "john_doe",
  "email": "john@example.com",
  "age": 25
}

响应格式标准

1. 统一响应结构

所有API响应必须遵循以下格式：

{
  "errcode": 0,
  "msg": "",
  "rcursor": [],
}

2. 响应参数说明

成功响应

{
  "errcode": 0,
  "msg": "",
  "rcursor": [
    {
      "userId": "usr_123456789",
      "username": "john_doe",
      "email": "john@example.com"
    }
  ],
}

错误响应

{
  "errcode": -1,
  "msg": "参数错误：用户名不能为空",
  "rcursor": [],
}

错误码规范

1. 通用错误码

错误码	说明	场景
0	成功	操作成功完成
-1	失败	参数缺失或格式错误

认证规范

1. Token认证

认证要求

本接口需要Bearer Token认证：

Authorization: Bearer <your-access-token>

Token获取方式参见：用户登录接口

分页规范

1. 请求参数

### 分页参数
| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| pageNumber | number | 否 | 页码，从1开始 | 1 |
| pageSize | number | 否 | 每页数量，默认10，最大100 | 20 |

2. 分页响应

参数名	类型	说明	示例
rcursor	array	数据列表	[...]
total	number	总记录数	100
pageNumber	number	当前页码	1
pageSize	number	每页数量	20