146 lines
2.5 KiB
Markdown
146 lines
2.5 KiB
Markdown
# 接口文档模板
|
|
|
|
## 接口信息
|
|
|
|
- **接口名称**: [接口名称]
|
|
- **接口路径**: [接口路径]
|
|
- **请求方法**: [GET|POST|PUT|DELETE]
|
|
- **模块归属**: [所属模块]
|
|
- **版本号**: v[版本号]
|
|
- **创建日期**: YYYY-MM-DD
|
|
- **最后更新**: YYYY-MM-DD
|
|
|
|
## 功能描述
|
|
|
|
[详细描述接口的功能和使用场景]
|
|
|
|
## 请求参数
|
|
|
|
### 路径参数
|
|
|
|
| 参数名 | 类型 | 必填 | 描述 | 示例 |
|
|
|--------|------|------|------|------|
|
|
| [参数名] | [类型] | [是/否] | [描述] | [示例] |
|
|
|
|
### 查询参数
|
|
|
|
| 参数名 | 类型 | 必填 | 描述 | 示例 | 默认值 |
|
|
|--------|------|------|------|------|--------|
|
|
| [参数名] | [类型] | [是/否] | [描述] | [示例] | [默认值] |
|
|
|
|
### 请求体 (JSON)
|
|
|
|
```json
|
|
{
|
|
"[参数名]": "[值]",
|
|
"[参数名]": "[值]"
|
|
}
|
|
```
|
|
|
|
| 参数名 | 类型 | 必填 | 描述 | 示例 |
|
|
|--------|------|------|------|------|
|
|
| [参数名] | [类型] | [是/否] | [描述] | [示例] |
|
|
|
|
## 响应数据
|
|
|
|
### 成功响应
|
|
|
|
**HTTP 状态码**: 200 OK
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"message": "操作成功",
|
|
"data": {
|
|
"[字段名]": "[值]",
|
|
"[字段名]": "[值]"
|
|
}
|
|
}
|
|
```
|
|
|
|
| 字段名 | 类型 | 描述 | 示例 |
|
|
|--------|------|------|------|
|
|
| [字段名] | [类型] | [描述] | [示例] |
|
|
|
|
### 失败响应
|
|
|
|
**HTTP 状态码**: [400|401|403|404|500]
|
|
|
|
```json
|
|
{
|
|
"code": [错误码],
|
|
"message": "[错误信息]",
|
|
"data": null
|
|
}
|
|
```
|
|
|
|
| 错误码 | 错误信息 | 描述 |
|
|
|--------|----------|------|
|
|
| [错误码] | [错误信息] | [描述] |
|
|
|
|
## 接口示例
|
|
|
|
### 请求示例
|
|
|
|
```bash
|
|
curl -X [方法] "[接口URL]" \
|
|
-H "Content-Type: application/json" \
|
|
-H "Authorization: Bearer [token]" \
|
|
-d '{
|
|
"[参数名]": "[值]"
|
|
}'
|
|
```
|
|
|
|
### 响应示例
|
|
|
|
**成功**:
|
|
|
|
```json
|
|
{
|
|
"code": 200,
|
|
"message": "操作成功",
|
|
"data": {
|
|
"id": "123",
|
|
"name": "示例数据"
|
|
}
|
|
}
|
|
```
|
|
|
|
**失败**:
|
|
|
|
```json
|
|
{
|
|
"code": 400,
|
|
"message": "参数错误",
|
|
"data": null
|
|
}
|
|
```
|
|
|
|
## 错误处理
|
|
|
|
[描述接口的错误处理机制和常见错误情况]
|
|
|
|
## 注意事项
|
|
|
|
[接口使用的注意事项和限制条件]
|
|
|
|
## 相关接口
|
|
|
|
- [相关接口名称](相关接口路径) - [描述]
|
|
|
|
## 实现细节
|
|
|
|
[接口的实现细节和技术要点]
|
|
|
|
## 测试信息
|
|
|
|
### 测试环境
|
|
|
|
- **环境**: [测试环境]
|
|
- **版本**: [版本号]
|
|
|
|
### 测试用例
|
|
|
|
| 测试场景 | 输入参数 | 预期结果 | 实际结果 | 状态 |
|
|
|----------|----------|----------|----------|------|
|
|
| [测试场景] | [输入参数] | [预期结果] | [实际结果] | [通过/失败] | |