API

好的！这是一个完整的 API 接口文档示例，使用 Markdown 格式，包含层级结构和完整要素：

# 📊 用户管理系统 API 文档
# 📊 用户管理系统 API 文档
## 📋 文档信息
- **版本**: v1.0.0
- **最后更新**: 2024-12-19
- **基础URL**: `https://api.example.com/v1`
- **认证方式**: Bearer Token

---

## 🔐 认证

### 获取访问令牌
**POST** `/auth/login`

#### 请求参数
| 参数名 | 类型 | 必需 | 描述 |
|--------|------|------|------|
| username | string | 是 | 用户名 |
| password | string | 是 | 密码 |

#### 请求示例
```json
{
  "username": "admin",
  "password": "123456"
}
```

#### 响应示例
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 3600
  }
}
```

#### 状态码
| 状态码 | 描述 |
|--------|------|
| 200 | 登录成功 |
| 401 | 用户名或密码错误 |
| 429 | 请求过于频繁 |

---

## 👥 用户管理

### 1. 用户信息

#### 1.1 获取用户列表
**GET** `/users`

##### 查询参数
| 参数名 |  必需 | 描述 |
|--------|------|------|------|
| page | integer | 否 | 页码，默认1 |
| limit | integer | 否 | 每页数量，默认20 |
| keyword | string | 否 | 搜索关键词 |

##### 响应示例
```json
{
  "code": 200,
  "data": {
    "list": [
      {
        "id": 1,
        "username": "zhangsan",
        "email": "zhangsan@example.com",
        "status": "active",
        "create_time": "2024-01-01T10:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit":       "total": 100
    }
  }
}
```

#### 1.2 获取用户详情
**GET** `/users/{id}`

##### 路径参数
| 参数名 | 类型 | 必需 | 描述 |
|--------|------|------|------|
| id | integer | 是 | 用户ID |

##### 响应示例
```json
{
  "code": 200,
  "data": {
    "id": 1,
    "username": "zhangsan",
    "email": "zhangsan@example.com",
    "profile": {
      "nickname": "张三",
      "avatar": "https://example.com/avatar.jpg",
      "bio": "软件工程师"
    },
    "status": "active",
    "create_time": "2024-01-01T10:00:00Z"
  }
}
```

#### 1.3 创建用户
**POST** `/users`

##### 请求头
```
Authorization: Bearer {token}
Content-Type: application/json
```

##### 请求体
```json
{
  "username": "lisi",
  "email": "lisi@example.com",
  "password": "password123",
  "profile": {
    "nickname": "李四",
    "avatar": "https://example.com/avatar.jpg"
  }
}
 响应状态码
| 状态码 | 描述 |
|--------|------|
| 201 | 创建成功 |
| 400 | 参数验证失败 |
| 409 | 用户名已存在 |

### 2. 用户操作

#### 2.1 更新用户信息
**PUT** `/users/{id}`

##### 请求体
```json
{
  "email": "newemail@example.com",
  "profile": {
    "nickname": "新昵称",
    "bio": "新的个人简介"
  }
}
```

#### 2.2 删除用户
**DELETE** `/users/{id}`

##### 响应示例
```json
{
  "code": 200,
  "message": "用户删除成功"
}
```

---

## 📁 文件管理

### 1. 文件上传

#### 1.1 单文件上传
**POST**`

##### 请求头
```
Content-Type: multipart/form-data
```

##### 表单数据
| 字段名 | 类型 | 必需 | 描述 |
|--------|------|------|------|
| file | file | 是 | 上传的文件 |
| category | string | 否 | 文件分类 |

##### 响应示例
```json
{
  "code": 200,
  "data": {
    "url": "https://cdn.example.com/files/abc.jpg",
    "size": 1024000,
    "mime_type": "image/jpeg"
  }
}
```

### 2. 文件管理

#### 2.1 获取文件列表
**GET** `/files`

#### 2.2 删除文件
**DELETE** `/files/{fileId}`

---

## ⚠️ 错误处理

### 错误响应格式
```json
{
  "code": 400,
  "message": "参数验证失败",
  "errors": [
    {
      "field": "username",
      "message": "用户名不能为空"
    }
  ],
  "request_id": "req_123456"
}
```

### 常见错误码
| 错误码 | 描述 | 解决方案 |
|--------|------|----------|
| 400 | 错误的请求 | 检查请求参数 |
| 401 | 未授权 | 提供有效的认证令牌 |
| 403 | 禁止访问 | 检查用户权限 |
| 404 | 资源不存在 | 检查请求路径 |
| 500 | 服务器内部错误 | 联系技术支持 |

---

## 🔄 更新日志

### v1.0.0 (2024-12-19)
- ✅ 新增用户管理相关接口
- ✅ 新增文件上传功能
- ✅ 完善错误处理机制

###.9.0 (2024-11-15)
- 🚀 初始版本发布

---

## 📞 技术支持

- **文档维护**: 技术团队
- **问题反馈**: mailto:issues@example.com
- **API状态**: https://status.example.com

这个文档展示了 Markdown 支持的各种功能：
- ✅ **多级标题** (#, ##, ###)
- ✅ **表格** (参数说明)
- ✅ **代码块** (JSON 示例)
- ✅ **列表** (有序和无序)
- ✅ **强调文本** (粗体、斜体)
- ✅ **链接和邮箱**
- ✅ **表情符号** (视觉增强)
- ✅ **水平分割线**

你可以直接复制这个 Markdown 内容到支持 Markdown 的编辑器中查看效果！