forked from datawhale/whale-town-end
docs：创建完整的API接口文档
- 创建详细的API接口说明文档 - 提供OpenAPI 3.0规范文件 - 创建Postman测试集合 - 添加API文档使用指南
This commit is contained in:
moyin
141
docs/api/README.md
Normal file
141
docs/api/README.md
Normal file
@@ -0,0 +1,141 @@
|
|||||||
|
# API接口文档
|
||||||
|
|
||||||
|
本目录包含了像素游戏服务器用户认证API的完整文档。
|
||||||
|
|
||||||
|
## 📋 文档文件说明
|
||||||
|
|
||||||
|
### 1. api-documentation.md
|
||||||
|
详细的API接口文档，包含：
|
||||||
|
- 接口概述和通用响应格式
|
||||||
|
- 每个接口的详细说明、参数、响应示例
|
||||||
|
- 错误代码说明
|
||||||
|
- 数据验证规则
|
||||||
|
- 使用示例（JavaScript/TypeScript 和 cURL）
|
||||||
|
|
||||||
|
### 2. openapi.yaml
|
||||||
|
OpenAPI 3.0规范文件，可以用于：
|
||||||
|
- 导入到Swagger Editor查看和编辑
|
||||||
|
- 生成客户端SDK
|
||||||
|
- 集成到API网关
|
||||||
|
- 自动化测试
|
||||||
|
|
||||||
|
### 3. postman-collection.json
|
||||||
|
Postman集合文件，包含：
|
||||||
|
- 所有API接口的请求示例
|
||||||
|
- 预设的请求参数
|
||||||
|
- 响应示例
|
||||||
|
- 可直接导入Postman进行测试
|
||||||
|
|
||||||
|
## 🚀 快速开始
|
||||||
|
|
||||||
|
### 1. 启动服务器并查看Swagger文档
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 启动开发服务器
|
||||||
|
pnpm run dev
|
||||||
|
|
||||||
|
# 访问Swagger UI
|
||||||
|
# 浏览器打开: http://localhost:3000/api-docs
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. 使用Postman测试API
|
||||||
|
|
||||||
|
1. 打开Postman
|
||||||
|
2. 点击 Import 按钮
|
||||||
|
3. 选择 `docs/api/postman-collection.json` 文件
|
||||||
|
4. 导入后即可看到所有API接口
|
||||||
|
5. 修改环境变量 `baseUrl` 为你的服务器地址（默认：http://localhost:3000）
|
||||||
|
|
||||||
|
### 3. 使用OpenAPI规范
|
||||||
|
|
||||||
|
#### 在Swagger Editor中查看
|
||||||
|
1. 访问 [Swagger Editor](https://editor.swagger.io/)
|
||||||
|
2. 将 `docs/api/openapi.yaml` 的内容复制粘贴到编辑器中
|
||||||
|
3. 即可查看可视化的API文档
|
||||||
|
|
||||||
|
#### 生成客户端SDK
|
||||||
|
```bash
|
||||||
|
# 使用swagger-codegen生成JavaScript客户端
|
||||||
|
swagger-codegen generate -i docs/api/openapi.yaml -l javascript -o ./client-sdk
|
||||||
|
|
||||||
|
# 使用openapi-generator生成TypeScript客户端
|
||||||
|
openapi-generator generate -i docs/api/openapi.yaml -g typescript-axios -o ./client-sdk
|
||||||
|
```
|
||||||
|
|
||||||
|
## 📊 API接口概览
|
||||||
|
|
||||||
|
| 接口 | 方法 | 路径 | 描述 |
|
||||||
|
|------|------|------|------|
|
||||||
|
| 用户登录 | POST | /auth/login | 支持用户名、邮箱或手机号登录 |
|
||||||
|
| 用户注册 | POST | /auth/register | 创建新用户账户 |
|
||||||
|
| GitHub OAuth | POST | /auth/github | 使用GitHub账户登录或注册 |
|
||||||
|
| 发送验证码 | POST | /auth/forgot-password | 发送密码重置验证码 |
|
||||||
|
| 重置密码 | POST | /auth/reset-password | 使用验证码重置密码 |
|
||||||
|
| 修改密码 | PUT | /auth/change-password | 修改用户密码 |
|
||||||
|
|
||||||
|
## 🧪 快速测试
|
||||||
|
|
||||||
|
### 使用cURL测试登录接口
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 测试用户登录
|
||||||
|
curl -X POST http://localhost:3000/auth/login \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d '{
|
||||||
|
"identifier": "testuser",
|
||||||
|
"password": "password123"
|
||||||
|
}'
|
||||||
|
|
||||||
|
# 测试用户注册
|
||||||
|
curl -X POST http://localhost:3000/auth/register \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d '{
|
||||||
|
"username": "newuser",
|
||||||
|
"password": "password123",
|
||||||
|
"nickname": "新用户",
|
||||||
|
"email": "newuser@example.com"
|
||||||
|
}'
|
||||||
|
```
|
||||||
|
|
||||||
|
### 使用JavaScript测试
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
// 用户登录
|
||||||
|
const response = await fetch('http://localhost:3000/auth/login', {
|
||||||
|
method: 'POST',
|
||||||
|
headers: {
|
||||||
|
'Content-Type': 'application/json',
|
||||||
|
},
|
||||||
|
body: JSON.stringify({
|
||||||
|
identifier: 'testuser',
|
||||||
|
password: 'password123'
|
||||||
|
})
|
||||||
|
});
|
||||||
|
|
||||||
|
const data = await response.json();
|
||||||
|
console.log(data);
|
||||||
|
```
|
||||||
|
|
||||||
|
## ⚠️ 注意事项
|
||||||
|
|
||||||
|
1. **开发环境**: 当前配置适用于开发环境，生产环境需要使用HTTPS
|
||||||
|
2. **认证**: 实际应用中应实现JWT认证机制
|
||||||
|
3. **限流**: 建议对认证接口实施限流策略
|
||||||
|
4. **验证码**: 示例中返回验证码仅用于演示，生产环境不应返回
|
||||||
|
5. **错误处理**: 建议实现统一的错误处理机制
|
||||||
|
|
||||||
|
## 🔄 更新文档
|
||||||
|
|
||||||
|
当API接口发生变化时，请同步更新以下文件：
|
||||||
|
1. 更新DTO类的Swagger装饰器
|
||||||
|
2. 更新 `api-documentation.md`
|
||||||
|
3. 更新 `openapi.yaml`
|
||||||
|
4. 更新 `postman-collection.json`
|
||||||
|
5. 重新生成Swagger文档
|
||||||
|
|
||||||
|
## 🔗 相关链接
|
||||||
|
|
||||||
|
- [NestJS Swagger文档](https://docs.nestjs.com/openapi/introduction)
|
||||||
|
- [OpenAPI规范](https://swagger.io/specification/)
|
||||||
|
- [Postman文档](https://learning.postman.com/docs/getting-started/introduction/)
|
||||||
|
- [Swagger Editor](https://editor.swagger.io/)
|
||||||
412
docs/api/api-documentation.md
Normal file
412
docs/api/api-documentation.md
Normal file
@@ -0,0 +1,412 @@
|
|||||||
|
# 用户认证API接口文档
|
||||||
|
|
||||||
|
## 概述
|
||||||
|
|
||||||
|
本文档描述了像素游戏服务器的用户认证相关API接口，包括登录、注册、密码找回等功能。
|
||||||
|
|
||||||
|
**基础URL**: `http://localhost:3000`
|
||||||
|
**API文档地址**: `http://localhost:3000/api-docs`
|
||||||
|
|
||||||
|
## 通用响应格式
|
||||||
|
|
||||||
|
所有API接口都遵循统一的响应格式：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"success": boolean,
|
||||||
|
"data": object | null,
|
||||||
|
"message": string,
|
||||||
|
"error_code": string | null
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 字段说明
|
||||||
|
|
||||||
|
- `success`: 请求是否成功
|
||||||
|
- `data`: 响应数据（成功时返回）
|
||||||
|
- `message`: 响应消息
|
||||||
|
- `error_code`: 错误代码（失败时返回）
|
||||||
|
|
||||||
|
## 接口列表
|
||||||
|
|
||||||
|
### 1. 用户登录
|
||||||
|
|
||||||
|
**接口地址**: `POST /auth/login`
|
||||||
|
|
||||||
|
**功能描述**: 用户登录，支持用户名、邮箱或手机号登录
|
||||||
|
|
||||||
|
#### 请求参数
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"identifier": "testuser",
|
||||||
|
"password": "password123"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
| 参数名 | 类型 | 必填 | 说明 |
|
||||||
|
|--------|------|------|------|
|
||||||
|
| identifier | string | 是 | 登录标识符，支持用户名、邮箱或手机号 |
|
||||||
|
| password | string | 是 | 用户密码 |
|
||||||
|
|
||||||
|
#### 响应示例
|
||||||
|
|
||||||
|
**成功响应** (200):
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"success": true,
|
||||||
|
"data": {
|
||||||
|
"user": {
|
||||||
|
"id": "1",
|
||||||
|
"username": "testuser",
|
||||||
|
"nickname": "测试用户",
|
||||||
|
"email": "test@example.com",
|
||||||
|
"phone": "+8613800138000",
|
||||||
|
"avatar_url": "https://example.com/avatar.jpg",
|
||||||
|
"role": 1,
|
||||||
|
"created_at": "2025-12-17T10:00:00.000Z"
|
||||||
|
},
|
||||||
|
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||||||
|
"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||||||
|
"is_new_user": false,
|
||||||
|
"message": "登录成功"
|
||||||
|
},
|
||||||
|
"message": "登录成功"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**失败响应** (401):
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"success": false,
|
||||||
|
"message": "用户名或密码错误",
|
||||||
|
"error_code": "LOGIN_FAILED"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. 用户注册
|
||||||
|
|
||||||
|
**接口地址**: `POST /auth/register`
|
||||||
|
|
||||||
|
**功能描述**: 创建新用户账户
|
||||||
|
|
||||||
|
#### 请求参数
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"username": "testuser",
|
||||||
|
"password": "password123",
|
||||||
|
"nickname": "测试用户",
|
||||||
|
"email": "test@example.com",
|
||||||
|
"phone": "+8613800138000"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
| 参数名 | 类型 | 必填 | 说明 |
|
||||||
|
|--------|------|------|------|
|
||||||
|
| username | string | 是 | 用户名，只能包含字母、数字和下划线，长度1-50字符 |
|
||||||
|
| password | string | 是 | 密码，必须包含字母和数字，长度8-128字符 |
|
||||||
|
| nickname | string | 是 | 用户昵称，长度1-50字符 |
|
||||||
|
| email | string | 否 | 邮箱地址 |
|
||||||
|
| phone | string | 否 | 手机号码 |
|
||||||
|
|
||||||
|
#### 响应示例
|
||||||
|
|
||||||
|
**成功响应** (201):
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"success": true,
|
||||||
|
"data": {
|
||||||
|
"user": {
|
||||||
|
"id": "2",
|
||||||
|
"username": "testuser",
|
||||||
|
"nickname": "测试用户",
|
||||||
|
"email": "test@example.com",
|
||||||
|
"phone": "+8613800138000",
|
||||||
|
"avatar_url": null,
|
||||||
|
"role": 1,
|
||||||
|
"created_at": "2025-12-17T10:00:00.000Z"
|
||||||
|
},
|
||||||
|
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||||||
|
"is_new_user": true,
|
||||||
|
"message": "注册成功"
|
||||||
|
},
|
||||||
|
"message": "注册成功"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**失败响应** (409):
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"success": false,
|
||||||
|
"message": "用户名已存在",
|
||||||
|
"error_code": "REGISTER_FAILED"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. GitHub OAuth登录
|
||||||
|
|
||||||
|
**接口地址**: `POST /auth/github`
|
||||||
|
|
||||||
|
**功能描述**: 使用GitHub账户登录或注册
|
||||||
|
|
||||||
|
#### 请求参数
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"github_id": "12345678",
|
||||||
|
"username": "octocat",
|
||||||
|
"nickname": "The Octocat",
|
||||||
|
"email": "octocat@github.com",
|
||||||
|
"avatar_url": "https://github.com/images/error/octocat_happy.gif"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
| 参数名 | 类型 | 必填 | 说明 |
|
||||||
|
|--------|------|------|------|
|
||||||
|
| github_id | string | 是 | GitHub用户ID |
|
||||||
|
| username | string | 是 | GitHub用户名 |
|
||||||
|
| nickname | string | 是 | GitHub显示名称 |
|
||||||
|
| email | string | 否 | GitHub邮箱地址 |
|
||||||
|
| avatar_url | string | 否 | GitHub头像URL |
|
||||||
|
|
||||||
|
#### 响应示例
|
||||||
|
|
||||||
|
**成功响应** (200):
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"success": true,
|
||||||
|
"data": {
|
||||||
|
"user": {
|
||||||
|
"id": "3",
|
||||||
|
"username": "octocat",
|
||||||
|
"nickname": "The Octocat",
|
||||||
|
"email": "octocat@github.com",
|
||||||
|
"phone": null,
|
||||||
|
"avatar_url": "https://github.com/images/error/octocat_happy.gif",
|
||||||
|
"role": 1,
|
||||||
|
"created_at": "2025-12-17T10:00:00.000Z"
|
||||||
|
},
|
||||||
|
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
||||||
|
"is_new_user": true,
|
||||||
|
"message": "GitHub账户绑定成功"
|
||||||
|
},
|
||||||
|
"message": "GitHub账户绑定成功"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. 发送密码重置验证码
|
||||||
|
|
||||||
|
**接口地址**: `POST /auth/forgot-password`
|
||||||
|
|
||||||
|
**功能描述**: 向用户邮箱或手机发送密码重置验证码
|
||||||
|
|
||||||
|
#### 请求参数
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"identifier": "test@example.com"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
| 参数名 | 类型 | 必填 | 说明 |
|
||||||
|
|--------|------|------|------|
|
||||||
|
| identifier | string | 是 | 邮箱或手机号 |
|
||||||
|
|
||||||
|
#### 响应示例
|
||||||
|
|
||||||
|
**成功响应** (200):
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"success": true,
|
||||||
|
"data": {
|
||||||
|
"verification_code": "123456"
|
||||||
|
},
|
||||||
|
"message": "验证码已发送，请查收"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**注意**: 实际应用中不应返回验证码，这里仅用于演示。
|
||||||
|
|
||||||
|
### 5. 重置密码
|
||||||
|
|
||||||
|
**接口地址**: `POST /auth/reset-password`
|
||||||
|
|
||||||
|
**功能描述**: 使用验证码重置用户密码
|
||||||
|
|
||||||
|
#### 请求参数
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"identifier": "test@example.com",
|
||||||
|
"verification_code": "123456",
|
||||||
|
"new_password": "newpassword123"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
| 参数名 | 类型 | 必填 | 说明 |
|
||||||
|
|--------|------|------|------|
|
||||||
|
| identifier | string | 是 | 邮箱或手机号 |
|
||||||
|
| verification_code | string | 是 | 6位数字验证码 |
|
||||||
|
| new_password | string | 是 | 新密码，必须包含字母和数字，长度8-128字符 |
|
||||||
|
|
||||||
|
#### 响应示例
|
||||||
|
|
||||||
|
**成功响应** (200):
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"success": true,
|
||||||
|
"message": "密码重置成功"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 6. 修改密码
|
||||||
|
|
||||||
|
**接口地址**: `PUT /auth/change-password`
|
||||||
|
|
||||||
|
**功能描述**: 用户修改自己的密码（需要提供旧密码）
|
||||||
|
|
||||||
|
#### 请求参数
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"user_id": "1",
|
||||||
|
"old_password": "oldpassword123",
|
||||||
|
"new_password": "newpassword123"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
| 参数名 | 类型 | 必填 | 说明 |
|
||||||
|
|--------|------|------|------|
|
||||||
|
| user_id | string | 是 | 用户ID（实际应用中应从JWT令牌中获取） |
|
||||||
|
| old_password | string | 是 | 当前密码 |
|
||||||
|
| new_password | string | 是 | 新密码，必须包含字母和数字，长度8-128字符 |
|
||||||
|
|
||||||
|
#### 响应示例
|
||||||
|
|
||||||
|
**成功响应** (200):
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"success": true,
|
||||||
|
"message": "密码修改成功"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## 错误代码说明
|
||||||
|
|
||||||
|
| 错误代码 | 说明 |
|
||||||
|
|----------|------|
|
||||||
|
| LOGIN_FAILED | 登录失败 |
|
||||||
|
| REGISTER_FAILED | 注册失败 |
|
||||||
|
| GITHUB_OAUTH_FAILED | GitHub OAuth失败 |
|
||||||
|
| SEND_CODE_FAILED | 发送验证码失败 |
|
||||||
|
| RESET_PASSWORD_FAILED | 重置密码失败 |
|
||||||
|
| CHANGE_PASSWORD_FAILED | 修改密码失败 |
|
||||||
|
|
||||||
|
## 数据验证规则
|
||||||
|
|
||||||
|
### 用户名规则
|
||||||
|
- 长度：1-50字符
|
||||||
|
- 格式：只能包含字母、数字和下划线
|
||||||
|
- 正则表达式：`^[a-zA-Z0-9_]+$`
|
||||||
|
|
||||||
|
### 密码规则
|
||||||
|
- 长度：8-128字符
|
||||||
|
- 格式：必须包含字母和数字
|
||||||
|
- 正则表达式：`^(?=.*[a-zA-Z])(?=.*\d)`
|
||||||
|
|
||||||
|
### 验证码规则
|
||||||
|
- 长度：6位数字
|
||||||
|
- 正则表达式：`^\d{6}$`
|
||||||
|
|
||||||
|
## 使用示例
|
||||||
|
|
||||||
|
### JavaScript/TypeScript 示例
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// 用户登录
|
||||||
|
const loginResponse = await fetch('http://localhost:3000/auth/login', {
|
||||||
|
method: 'POST',
|
||||||
|
headers: {
|
||||||
|
'Content-Type': 'application/json',
|
||||||
|
},
|
||||||
|
body: JSON.stringify({
|
||||||
|
identifier: 'testuser',
|
||||||
|
password: 'password123'
|
||||||
|
})
|
||||||
|
});
|
||||||
|
|
||||||
|
const loginData = await loginResponse.json();
|
||||||
|
if (loginData.success) {
|
||||||
|
const token = loginData.data.access_token;
|
||||||
|
// 保存token用于后续请求
|
||||||
|
localStorage.setItem('token', token);
|
||||||
|
}
|
||||||
|
|
||||||
|
// 用户注册
|
||||||
|
const registerResponse = await fetch('http://localhost:3000/auth/register', {
|
||||||
|
method: 'POST',
|
||||||
|
headers: {
|
||||||
|
'Content-Type': 'application/json',
|
||||||
|
},
|
||||||
|
body: JSON.stringify({
|
||||||
|
username: 'newuser',
|
||||||
|
password: 'password123',
|
||||||
|
nickname: '新用户',
|
||||||
|
email: 'newuser@example.com'
|
||||||
|
})
|
||||||
|
});
|
||||||
|
|
||||||
|
const registerData = await registerResponse.json();
|
||||||
|
```
|
||||||
|
|
||||||
|
### cURL 示例
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 用户登录
|
||||||
|
curl -X POST http://localhost:3000/auth/login \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d '{
|
||||||
|
"identifier": "testuser",
|
||||||
|
"password": "password123"
|
||||||
|
}'
|
||||||
|
|
||||||
|
# 用户注册
|
||||||
|
curl -X POST http://localhost:3000/auth/register \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d '{
|
||||||
|
"username": "newuser",
|
||||||
|
"password": "password123",
|
||||||
|
"nickname": "新用户",
|
||||||
|
"email": "newuser@example.com"
|
||||||
|
}'
|
||||||
|
|
||||||
|
# 发送密码重置验证码
|
||||||
|
curl -X POST http://localhost:3000/auth/forgot-password \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d '{
|
||||||
|
"identifier": "test@example.com"
|
||||||
|
}'
|
||||||
|
|
||||||
|
# 重置密码
|
||||||
|
curl -X POST http://localhost:3000/auth/reset-password \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d '{
|
||||||
|
"identifier": "test@example.com",
|
||||||
|
"verification_code": "123456",
|
||||||
|
"new_password": "newpassword123"
|
||||||
|
}'
|
||||||
|
```
|
||||||
|
|
||||||
|
## 注意事项
|
||||||
|
|
||||||
|
1. **安全性**: 实际应用中应使用HTTPS协议
|
||||||
|
2. **令牌**: 示例中的access_token是简单的Base64编码，实际应用中应使用JWT
|
||||||
|
3. **验证码**: 实际应用中不应在响应中返回验证码
|
||||||
|
4. **用户ID**: 修改密码接口中的user_id应从JWT令牌中获取，而不是从请求体中传递
|
||||||
|
5. **错误处理**: 建议在客户端实现适当的错误处理和用户提示
|
||||||
|
6. **限流**: 建议对登录、注册等接口实施限流策略
|
||||||
|
|
||||||
|
## 更新日志
|
||||||
|
|
||||||
|
- **v1.0.0** (2025-12-17): 初始版本，包含基础的用户认证功能
|
||||||
568
docs/api/openapi.yaml
Normal file
568
docs/api/openapi.yaml
Normal file
@@ -0,0 +1,568 @@
|
|||||||
|
openapi: 3.0.3
|
||||||
|
info:
|
||||||
|
title: Pixel Game Server - Auth API
|
||||||
|
description: 像素游戏服务器用户认证API接口文档
|
||||||
|
version: 1.0.0
|
||||||
|
contact:
|
||||||
|
name: API Support
|
||||||
|
email: support@example.com
|
||||||
|
license:
|
||||||
|
name: MIT
|
||||||
|
url: https://opensource.org/licenses/MIT
|
||||||
|
|
||||||
|
servers:
|
||||||
|
- url: http://localhost:3000
|
||||||
|
description: 开发环境
|
||||||
|
|
||||||
|
tags:
|
||||||
|
- name: auth
|
||||||
|
description: 用户认证相关接口
|
||||||
|
|
||||||
|
paths:
|
||||||
|
/auth/login:
|
||||||
|
post:
|
||||||
|
tags:
|
||||||
|
- auth
|
||||||
|
summary: 用户登录
|
||||||
|
description: 支持用户名、邮箱或手机号登录
|
||||||
|
operationId: login
|
||||||
|
requestBody:
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/LoginDto'
|
||||||
|
example:
|
||||||
|
identifier: testuser
|
||||||
|
password: password123
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: 登录成功
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/LoginResponse'
|
||||||
|
example:
|
||||||
|
success: true
|
||||||
|
data:
|
||||||
|
user:
|
||||||
|
id: "1"
|
||||||
|
username: testuser
|
||||||
|
nickname: 测试用户
|
||||||
|
email: test@example.com
|
||||||
|
phone: "+8613800138000"
|
||||||
|
avatar_url: https://example.com/avatar.jpg
|
||||||
|
role: 1
|
||||||
|
created_at: "2025-12-17T10:00:00.000Z"
|
||||||
|
access_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||||||
|
refresh_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||||||
|
is_new_user: false
|
||||||
|
message: 登录成功
|
||||||
|
message: 登录成功
|
||||||
|
'400':
|
||||||
|
description: 请求参数错误
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/ErrorResponse'
|
||||||
|
'401':
|
||||||
|
description: 用户名或密码错误
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/ErrorResponse'
|
||||||
|
|
||||||
|
/auth/register:
|
||||||
|
post:
|
||||||
|
tags:
|
||||||
|
- auth
|
||||||
|
summary: 用户注册
|
||||||
|
description: 创建新用户账户
|
||||||
|
operationId: register
|
||||||
|
requestBody:
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/RegisterDto'
|
||||||
|
example:
|
||||||
|
username: newuser
|
||||||
|
password: password123
|
||||||
|
nickname: 新用户
|
||||||
|
email: newuser@example.com
|
||||||
|
phone: "+8613800138001"
|
||||||
|
responses:
|
||||||
|
'201':
|
||||||
|
description: 注册成功
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/RegisterResponse'
|
||||||
|
'400':
|
||||||
|
description: 请求参数错误
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/ErrorResponse'
|
||||||
|
'409':
|
||||||
|
description: 用户名或邮箱已存在
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/ErrorResponse'
|
||||||
|
|
||||||
|
/auth/github:
|
||||||
|
post:
|
||||||
|
tags:
|
||||||
|
- auth
|
||||||
|
summary: GitHub OAuth登录
|
||||||
|
description: 使用GitHub账户登录或注册
|
||||||
|
operationId: githubOAuth
|
||||||
|
requestBody:
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/GitHubOAuthDto'
|
||||||
|
example:
|
||||||
|
github_id: "12345678"
|
||||||
|
username: octocat
|
||||||
|
nickname: The Octocat
|
||||||
|
email: octocat@github.com
|
||||||
|
avatar_url: https://github.com/images/error/octocat_happy.gif
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: GitHub登录成功
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/GitHubOAuthResponse'
|
||||||
|
'400':
|
||||||
|
description: 请求参数错误
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/ErrorResponse'
|
||||||
|
'401':
|
||||||
|
description: GitHub认证失败
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/ErrorResponse'
|
||||||
|
|
||||||
|
/auth/forgot-password:
|
||||||
|
post:
|
||||||
|
tags:
|
||||||
|
- auth
|
||||||
|
summary: 发送密码重置验证码
|
||||||
|
description: 向用户邮箱或手机发送密码重置验证码
|
||||||
|
operationId: forgotPassword
|
||||||
|
requestBody:
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/ForgotPasswordDto'
|
||||||
|
example:
|
||||||
|
identifier: test@example.com
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: 验证码发送成功
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/ForgotPasswordResponse'
|
||||||
|
'400':
|
||||||
|
description: 请求参数错误
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/ErrorResponse'
|
||||||
|
'404':
|
||||||
|
description: 用户不存在
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/ErrorResponse'
|
||||||
|
|
||||||
|
/auth/reset-password:
|
||||||
|
post:
|
||||||
|
tags:
|
||||||
|
- auth
|
||||||
|
summary: 重置密码
|
||||||
|
description: 使用验证码重置用户密码
|
||||||
|
operationId: resetPassword
|
||||||
|
requestBody:
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/ResetPasswordDto'
|
||||||
|
example:
|
||||||
|
identifier: test@example.com
|
||||||
|
verification_code: "123456"
|
||||||
|
new_password: newpassword123
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: 密码重置成功
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/CommonResponse'
|
||||||
|
'400':
|
||||||
|
description: 请求参数错误或验证码无效
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/ErrorResponse'
|
||||||
|
'404':
|
||||||
|
description: 用户不存在
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/ErrorResponse'
|
||||||
|
|
||||||
|
/auth/change-password:
|
||||||
|
put:
|
||||||
|
tags:
|
||||||
|
- auth
|
||||||
|
summary: 修改密码
|
||||||
|
description: 用户修改自己的密码（需要提供旧密码）
|
||||||
|
operationId: changePassword
|
||||||
|
requestBody:
|
||||||
|
required: true
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/ChangePasswordDto'
|
||||||
|
example:
|
||||||
|
user_id: "1"
|
||||||
|
old_password: oldpassword123
|
||||||
|
new_password: newpassword123
|
||||||
|
responses:
|
||||||
|
'200':
|
||||||
|
description: 密码修改成功
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/CommonResponse'
|
||||||
|
'400':
|
||||||
|
description: 请求参数错误或旧密码不正确
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/ErrorResponse'
|
||||||
|
'404':
|
||||||
|
description: 用户不存在
|
||||||
|
content:
|
||||||
|
application/json:
|
||||||
|
schema:
|
||||||
|
$ref: '#/components/schemas/ErrorResponse'
|
||||||
|
|
||||||
|
components:
|
||||||
|
schemas:
|
||||||
|
LoginDto:
|
||||||
|
type: object
|
||||||
|
required:
|
||||||
|
- identifier
|
||||||
|
- password
|
||||||
|
properties:
|
||||||
|
identifier:
|
||||||
|
type: string
|
||||||
|
description: 登录标识符，支持用户名、邮箱或手机号
|
||||||
|
minLength: 1
|
||||||
|
maxLength: 100
|
||||||
|
example: testuser
|
||||||
|
password:
|
||||||
|
type: string
|
||||||
|
description: 用户密码
|
||||||
|
minLength: 1
|
||||||
|
maxLength: 128
|
||||||
|
example: password123
|
||||||
|
|
||||||
|
RegisterDto:
|
||||||
|
type: object
|
||||||
|
required:
|
||||||
|
- username
|
||||||
|
- password
|
||||||
|
- nickname
|
||||||
|
properties:
|
||||||
|
username:
|
||||||
|
type: string
|
||||||
|
description: 用户名，只能包含字母、数字和下划线
|
||||||
|
minLength: 1
|
||||||
|
maxLength: 50
|
||||||
|
pattern: '^[a-zA-Z0-9_]+$'
|
||||||
|
example: testuser
|
||||||
|
password:
|
||||||
|
type: string
|
||||||
|
description: 密码，必须包含字母和数字，长度8-128字符
|
||||||
|
minLength: 8
|
||||||
|
maxLength: 128
|
||||||
|
pattern: '^(?=.*[a-zA-Z])(?=.*\d)'
|
||||||
|
example: password123
|
||||||
|
nickname:
|
||||||
|
type: string
|
||||||
|
description: 用户昵称
|
||||||
|
minLength: 1
|
||||||
|
maxLength: 50
|
||||||
|
example: 测试用户
|
||||||
|
email:
|
||||||
|
type: string
|
||||||
|
format: email
|
||||||
|
description: 邮箱地址（可选）
|
||||||
|
example: test@example.com
|
||||||
|
phone:
|
||||||
|
type: string
|
||||||
|
description: 手机号码（可选）
|
||||||
|
example: "+8613800138000"
|
||||||
|
|
||||||
|
GitHubOAuthDto:
|
||||||
|
type: object
|
||||||
|
required:
|
||||||
|
- github_id
|
||||||
|
- username
|
||||||
|
- nickname
|
||||||
|
properties:
|
||||||
|
github_id:
|
||||||
|
type: string
|
||||||
|
description: GitHub用户ID
|
||||||
|
minLength: 1
|
||||||
|
maxLength: 100
|
||||||
|
example: "12345678"
|
||||||
|
username:
|
||||||
|
type: string
|
||||||
|
description: GitHub用户名
|
||||||
|
minLength: 1
|
||||||
|
maxLength: 50
|
||||||
|
example: octocat
|
||||||
|
nickname:
|
||||||
|
type: string
|
||||||
|
description: GitHub显示名称
|
||||||
|
minLength: 1
|
||||||
|
maxLength: 50
|
||||||
|
example: The Octocat
|
||||||
|
email:
|
||||||
|
type: string
|
||||||
|
format: email
|
||||||
|
description: GitHub邮箱地址（可选）
|
||||||
|
example: octocat@github.com
|
||||||
|
avatar_url:
|
||||||
|
type: string
|
||||||
|
description: GitHub头像URL（可选）
|
||||||
|
example: https://github.com/images/error/octocat_happy.gif
|
||||||
|
|
||||||
|
ForgotPasswordDto:
|
||||||
|
type: object
|
||||||
|
required:
|
||||||
|
- identifier
|
||||||
|
properties:
|
||||||
|
identifier:
|
||||||
|
type: string
|
||||||
|
description: 邮箱或手机号
|
||||||
|
minLength: 1
|
||||||
|
maxLength: 100
|
||||||
|
example: test@example.com
|
||||||
|
|
||||||
|
ResetPasswordDto:
|
||||||
|
type: object
|
||||||
|
required:
|
||||||
|
- identifier
|
||||||
|
- verification_code
|
||||||
|
- new_password
|
||||||
|
properties:
|
||||||
|
identifier:
|
||||||
|
type: string
|
||||||
|
description: 邮箱或手机号
|
||||||
|
minLength: 1
|
||||||
|
maxLength: 100
|
||||||
|
example: test@example.com
|
||||||
|
verification_code:
|
||||||
|
type: string
|
||||||
|
description: 6位数字验证码
|
||||||
|
pattern: '^\d{6}$'
|
||||||
|
example: "123456"
|
||||||
|
new_password:
|
||||||
|
type: string
|
||||||
|
description: 新密码，必须包含字母和数字，长度8-128字符
|
||||||
|
minLength: 8
|
||||||
|
maxLength: 128
|
||||||
|
pattern: '^(?=.*[a-zA-Z])(?=.*\d)'
|
||||||
|
example: newpassword123
|
||||||
|
|
||||||
|
ChangePasswordDto:
|
||||||
|
type: object
|
||||||
|
required:
|
||||||
|
- user_id
|
||||||
|
- old_password
|
||||||
|
- new_password
|
||||||
|
properties:
|
||||||
|
user_id:
|
||||||
|
type: string
|
||||||
|
description: 用户ID（实际应用中应从JWT令牌中获取）
|
||||||
|
example: "1"
|
||||||
|
old_password:
|
||||||
|
type: string
|
||||||
|
description: 当前密码
|
||||||
|
minLength: 1
|
||||||
|
maxLength: 128
|
||||||
|
example: oldpassword123
|
||||||
|
new_password:
|
||||||
|
type: string
|
||||||
|
description: 新密码，必须包含字母和数字，长度8-128字符
|
||||||
|
minLength: 8
|
||||||
|
maxLength: 128
|
||||||
|
pattern: '^(?=.*[a-zA-Z])(?=.*\d)'
|
||||||
|
example: newpassword123
|
||||||
|
|
||||||
|
UserInfo:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
id:
|
||||||
|
type: string
|
||||||
|
description: 用户ID
|
||||||
|
example: "1"
|
||||||
|
username:
|
||||||
|
type: string
|
||||||
|
description: 用户名
|
||||||
|
example: testuser
|
||||||
|
nickname:
|
||||||
|
type: string
|
||||||
|
description: 用户昵称
|
||||||
|
example: 测试用户
|
||||||
|
email:
|
||||||
|
type: string
|
||||||
|
format: email
|
||||||
|
description: 邮箱地址
|
||||||
|
example: test@example.com
|
||||||
|
phone:
|
||||||
|
type: string
|
||||||
|
description: 手机号码
|
||||||
|
example: "+8613800138000"
|
||||||
|
avatar_url:
|
||||||
|
type: string
|
||||||
|
description: 头像URL
|
||||||
|
example: https://example.com/avatar.jpg
|
||||||
|
role:
|
||||||
|
type: integer
|
||||||
|
description: 用户角色
|
||||||
|
example: 1
|
||||||
|
created_at:
|
||||||
|
type: string
|
||||||
|
format: date-time
|
||||||
|
description: 创建时间
|
||||||
|
example: "2025-12-17T10:00:00.000Z"
|
||||||
|
|
||||||
|
LoginResponseData:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
user:
|
||||||
|
$ref: '#/components/schemas/UserInfo'
|
||||||
|
access_token:
|
||||||
|
type: string
|
||||||
|
description: 访问令牌
|
||||||
|
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||||||
|
refresh_token:
|
||||||
|
type: string
|
||||||
|
description: 刷新令牌
|
||||||
|
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
||||||
|
is_new_user:
|
||||||
|
type: boolean
|
||||||
|
description: 是否为新用户
|
||||||
|
example: false
|
||||||
|
message:
|
||||||
|
type: string
|
||||||
|
description: 响应消息
|
||||||
|
example: 登录成功
|
||||||
|
|
||||||
|
LoginResponse:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
success:
|
||||||
|
type: boolean
|
||||||
|
description: 请求是否成功
|
||||||
|
example: true
|
||||||
|
data:
|
||||||
|
$ref: '#/components/schemas/LoginResponseData'
|
||||||
|
message:
|
||||||
|
type: string
|
||||||
|
description: 响应消息
|
||||||
|
example: 登录成功
|
||||||
|
|
||||||
|
RegisterResponse:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
success:
|
||||||
|
type: boolean
|
||||||
|
description: 请求是否成功
|
||||||
|
example: true
|
||||||
|
data:
|
||||||
|
$ref: '#/components/schemas/LoginResponseData'
|
||||||
|
message:
|
||||||
|
type: string
|
||||||
|
description: 响应消息
|
||||||
|
example: 注册成功
|
||||||
|
|
||||||
|
GitHubOAuthResponse:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
success:
|
||||||
|
type: boolean
|
||||||
|
description: 请求是否成功
|
||||||
|
example: true
|
||||||
|
data:
|
||||||
|
$ref: '#/components/schemas/LoginResponseData'
|
||||||
|
message:
|
||||||
|
type: string
|
||||||
|
description: 响应消息
|
||||||
|
example: GitHub登录成功
|
||||||
|
|
||||||
|
ForgotPasswordResponseData:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
verification_code:
|
||||||
|
type: string
|
||||||
|
description: 验证码（仅用于演示，实际应用中不应返回）
|
||||||
|
example: "123456"
|
||||||
|
|
||||||
|
ForgotPasswordResponse:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
success:
|
||||||
|
type: boolean
|
||||||
|
description: 请求是否成功
|
||||||
|
example: true
|
||||||
|
data:
|
||||||
|
$ref: '#/components/schemas/ForgotPasswordResponseData'
|
||||||
|
message:
|
||||||
|
type: string
|
||||||
|
description: 响应消息
|
||||||
|
example: 验证码已发送，请查收
|
||||||
|
|
||||||
|
CommonResponse:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
success:
|
||||||
|
type: boolean
|
||||||
|
description: 请求是否成功
|
||||||
|
example: true
|
||||||
|
message:
|
||||||
|
type: string
|
||||||
|
description: 响应消息
|
||||||
|
example: 操作成功
|
||||||
|
|
||||||
|
ErrorResponse:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
success:
|
||||||
|
type: boolean
|
||||||
|
description: 请求是否成功
|
||||||
|
example: false
|
||||||
|
message:
|
||||||
|
type: string
|
||||||
|
description: 错误消息
|
||||||
|
example: 操作失败
|
||||||
|
error_code:
|
||||||
|
type: string
|
||||||
|
description: 错误代码
|
||||||
|
example: OPERATION_FAILED
|
||||||
347
docs/api/postman-collection.json
Normal file
347
docs/api/postman-collection.json
Normal file
@@ -0,0 +1,347 @@
|
|||||||
|
{
|
||||||
|
"info": {
|
||||||
|
"name": "Pixel Game Server - Auth API",
|
||||||
|
"description": "像素游戏服务器用户认证API接口集合",
|
||||||
|
"version": "1.0.0",
|
||||||
|
"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
|
||||||
|
},
|
||||||
|
"variable": [
|
||||||
|
{
|
||||||
|
"key": "baseUrl",
|
||||||
|
"value": "http://localhost:3000",
|
||||||
|
"type": "string"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"item": [
|
||||||
|
{
|
||||||
|
"name": "用户登录",
|
||||||
|
"request": {
|
||||||
|
"method": "POST",
|
||||||
|
"header": [
|
||||||
|
{
|
||||||
|
"key": "Content-Type",
|
||||||
|
"value": "application/json"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"body": {
|
||||||
|
"mode": "raw",
|
||||||
|
"raw": "{\n \"identifier\": \"testuser\",\n \"password\": \"password123\"\n}"
|
||||||
|
},
|
||||||
|
"url": {
|
||||||
|
"raw": "{{baseUrl}}/auth/login",
|
||||||
|
"host": ["{{baseUrl}}"],
|
||||||
|
"path": ["auth", "login"]
|
||||||
|
},
|
||||||
|
"description": "用户登录接口，支持用户名、邮箱或手机号登录"
|
||||||
|
},
|
||||||
|
"response": [
|
||||||
|
{
|
||||||
|
"name": "登录成功",
|
||||||
|
"originalRequest": {
|
||||||
|
"method": "POST",
|
||||||
|
"header": [
|
||||||
|
{
|
||||||
|
"key": "Content-Type",
|
||||||
|
"value": "application/json"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"body": {
|
||||||
|
"mode": "raw",
|
||||||
|
"raw": "{\n \"identifier\": \"testuser\",\n \"password\": \"password123\"\n}"
|
||||||
|
},
|
||||||
|
"url": {
|
||||||
|
"raw": "{{baseUrl}}/auth/login",
|
||||||
|
"host": ["{{baseUrl}}"],
|
||||||
|
"path": ["auth", "login"]
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"status": "OK",
|
||||||
|
"code": 200,
|
||||||
|
"_postman_previewlanguage": "json",
|
||||||
|
"header": [
|
||||||
|
{
|
||||||
|
"key": "Content-Type",
|
||||||
|
"value": "application/json"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"body": "{\n \"success\": true,\n \"data\": {\n \"user\": {\n \"id\": \"1\",\n \"username\": \"testuser\",\n \"nickname\": \"测试用户\",\n \"email\": \"test@example.com\",\n \"phone\": \"+8613800138000\",\n \"avatar_url\": \"https://example.com/avatar.jpg\",\n \"role\": 1,\n \"created_at\": \"2025-12-17T10:00:00.000Z\"\n },\n \"access_token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n \"refresh_token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n \"is_new_user\": false,\n \"message\": \"登录成功\"\n },\n \"message\": \"登录成功\"\n}"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "用户注册",
|
||||||
|
"request": {
|
||||||
|
"method": "POST",
|
||||||
|
"header": [
|
||||||
|
{
|
||||||
|
"key": "Content-Type",
|
||||||
|
"value": "application/json"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"body": {
|
||||||
|
"mode": "raw",
|
||||||
|
"raw": "{\n \"username\": \"newuser\",\n \"password\": \"password123\",\n \"nickname\": \"新用户\",\n \"email\": \"newuser@example.com\",\n \"phone\": \"+8613800138001\"\n}"
|
||||||
|
},
|
||||||
|
"url": {
|
||||||
|
"raw": "{{baseUrl}}/auth/register",
|
||||||
|
"host": ["{{baseUrl}}"],
|
||||||
|
"path": ["auth", "register"]
|
||||||
|
},
|
||||||
|
"description": "用户注册接口，创建新用户账户"
|
||||||
|
},
|
||||||
|
"response": [
|
||||||
|
{
|
||||||
|
"name": "注册成功",
|
||||||
|
"originalRequest": {
|
||||||
|
"method": "POST",
|
||||||
|
"header": [
|
||||||
|
{
|
||||||
|
"key": "Content-Type",
|
||||||
|
"value": "application/json"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"body": {
|
||||||
|
"mode": "raw",
|
||||||
|
"raw": "{\n \"username\": \"newuser\",\n \"password\": \"password123\",\n \"nickname\": \"新用户\",\n \"email\": \"newuser@example.com\",\n \"phone\": \"+8613800138001\"\n}"
|
||||||
|
},
|
||||||
|
"url": {
|
||||||
|
"raw": "{{baseUrl}}/auth/register",
|
||||||
|
"host": ["{{baseUrl}}"],
|
||||||
|
"path": ["auth", "register"]
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"status": "Created",
|
||||||
|
"code": 201,
|
||||||
|
"_postman_previewlanguage": "json",
|
||||||
|
"header": [
|
||||||
|
{
|
||||||
|
"key": "Content-Type",
|
||||||
|
"value": "application/json"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"body": "{\n \"success\": true,\n \"data\": {\n \"user\": {\n \"id\": \"2\",\n \"username\": \"newuser\",\n \"nickname\": \"新用户\",\n \"email\": \"newuser@example.com\",\n \"phone\": \"+8613800138001\",\n \"avatar_url\": null,\n \"role\": 1,\n \"created_at\": \"2025-12-17T10:00:00.000Z\"\n },\n \"access_token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n \"is_new_user\": true,\n \"message\": \"注册成功\"\n },\n \"message\": \"注册成功\"\n}"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "GitHub OAuth登录",
|
||||||
|
"request": {
|
||||||
|
"method": "POST",
|
||||||
|
"header": [
|
||||||
|
{
|
||||||
|
"key": "Content-Type",
|
||||||
|
"value": "application/json"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"body": {
|
||||||
|
"mode": "raw",
|
||||||
|
"raw": "{\n \"github_id\": \"12345678\",\n \"username\": \"octocat\",\n \"nickname\": \"The Octocat\",\n \"email\": \"octocat@github.com\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\"\n}"
|
||||||
|
},
|
||||||
|
"url": {
|
||||||
|
"raw": "{{baseUrl}}/auth/github",
|
||||||
|
"host": ["{{baseUrl}}"],
|
||||||
|
"path": ["auth", "github"]
|
||||||
|
},
|
||||||
|
"description": "GitHub OAuth登录接口，使用GitHub账户登录或注册"
|
||||||
|
},
|
||||||
|
"response": [
|
||||||
|
{
|
||||||
|
"name": "GitHub登录成功",
|
||||||
|
"originalRequest": {
|
||||||
|
"method": "POST",
|
||||||
|
"header": [
|
||||||
|
{
|
||||||
|
"key": "Content-Type",
|
||||||
|
"value": "application/json"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"body": {
|
||||||
|
"mode": "raw",
|
||||||
|
"raw": "{\n \"github_id\": \"12345678\",\n \"username\": \"octocat\",\n \"nickname\": \"The Octocat\",\n \"email\": \"octocat@github.com\",\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\"\n}"
|
||||||
|
},
|
||||||
|
"url": {
|
||||||
|
"raw": "{{baseUrl}}/auth/github",
|
||||||
|
"host": ["{{baseUrl}}"],
|
||||||
|
"path": ["auth", "github"]
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"status": "OK",
|
||||||
|
"code": 200,
|
||||||
|
"_postman_previewlanguage": "json",
|
||||||
|
"header": [
|
||||||
|
{
|
||||||
|
"key": "Content-Type",
|
||||||
|
"value": "application/json"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"body": "{\n \"success\": true,\n \"data\": {\n \"user\": {\n \"id\": \"3\",\n \"username\": \"octocat\",\n \"nickname\": \"The Octocat\",\n \"email\": \"octocat@github.com\",\n \"phone\": null,\n \"avatar_url\": \"https://github.com/images/error/octocat_happy.gif\",\n \"role\": 1,\n \"created_at\": \"2025-12-17T10:00:00.000Z\"\n },\n \"access_token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n \"is_new_user\": true,\n \"message\": \"GitHub账户绑定成功\"\n },\n \"message\": \"GitHub账户绑定成功\"\n}"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "发送密码重置验证码",
|
||||||
|
"request": {
|
||||||
|
"method": "POST",
|
||||||
|
"header": [
|
||||||
|
{
|
||||||
|
"key": "Content-Type",
|
||||||
|
"value": "application/json"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"body": {
|
||||||
|
"mode": "raw",
|
||||||
|
"raw": "{\n \"identifier\": \"test@example.com\"\n}"
|
||||||
|
},
|
||||||
|
"url": {
|
||||||
|
"raw": "{{baseUrl}}/auth/forgot-password",
|
||||||
|
"host": ["{{baseUrl}}"],
|
||||||
|
"path": ["auth", "forgot-password"]
|
||||||
|
},
|
||||||
|
"description": "发送密码重置验证码到用户邮箱或手机"
|
||||||
|
},
|
||||||
|
"response": [
|
||||||
|
{
|
||||||
|
"name": "验证码发送成功",
|
||||||
|
"originalRequest": {
|
||||||
|
"method": "POST",
|
||||||
|
"header": [
|
||||||
|
{
|
||||||
|
"key": "Content-Type",
|
||||||
|
"value": "application/json"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"body": {
|
||||||
|
"mode": "raw",
|
||||||
|
"raw": "{\n \"identifier\": \"test@example.com\"\n}"
|
||||||
|
},
|
||||||
|
"url": {
|
||||||
|
"raw": "{{baseUrl}}/auth/forgot-password",
|
||||||
|
"host": ["{{baseUrl}}"],
|
||||||
|
"path": ["auth", "forgot-password"]
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"status": "OK",
|
||||||
|
"code": 200,
|
||||||
|
"_postman_previewlanguage": "json",
|
||||||
|
"header": [
|
||||||
|
{
|
||||||
|
"key": "Content-Type",
|
||||||
|
"value": "application/json"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"body": "{\n \"success\": true,\n \"data\": {\n \"verification_code\": \"123456\"\n },\n \"message\": \"验证码已发送，请查收\"\n}"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "重置密码",
|
||||||
|
"request": {
|
||||||
|
"method": "POST",
|
||||||
|
"header": [
|
||||||
|
{
|
||||||
|
"key": "Content-Type",
|
||||||
|
"value": "application/json"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"body": {
|
||||||
|
"mode": "raw",
|
||||||
|
"raw": "{\n \"identifier\": \"test@example.com\",\n \"verification_code\": \"123456\",\n \"new_password\": \"newpassword123\"\n}"
|
||||||
|
},
|
||||||
|
"url": {
|
||||||
|
"raw": "{{baseUrl}}/auth/reset-password",
|
||||||
|
"host": ["{{baseUrl}}"],
|
||||||
|
"path": ["auth", "reset-password"]
|
||||||
|
},
|
||||||
|
"description": "使用验证码重置用户密码"
|
||||||
|
},
|
||||||
|
"response": [
|
||||||
|
{
|
||||||
|
"name": "密码重置成功",
|
||||||
|
"originalRequest": {
|
||||||
|
"method": "POST",
|
||||||
|
"header": [
|
||||||
|
{
|
||||||
|
"key": "Content-Type",
|
||||||
|
"value": "application/json"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"body": {
|
||||||
|
"mode": "raw",
|
||||||
|
"raw": "{\n \"identifier\": \"test@example.com\",\n \"verification_code\": \"123456\",\n \"new_password\": \"newpassword123\"\n}"
|
||||||
|
},
|
||||||
|
"url": {
|
||||||
|
"raw": "{{baseUrl}}/auth/reset-password",
|
||||||
|
"host": ["{{baseUrl}}"],
|
||||||
|
"path": ["auth", "reset-password"]
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"status": "OK",
|
||||||
|
"code": 200,
|
||||||
|
"_postman_previewlanguage": "json",
|
||||||
|
"header": [
|
||||||
|
{
|
||||||
|
"key": "Content-Type",
|
||||||
|
"value": "application/json"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"body": "{\n \"success\": true,\n \"message\": \"密码重置成功\"\n}"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "修改密码",
|
||||||
|
"request": {
|
||||||
|
"method": "PUT",
|
||||||
|
"header": [
|
||||||
|
{
|
||||||
|
"key": "Content-Type",
|
||||||
|
"value": "application/json"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"body": {
|
||||||
|
"mode": "raw",
|
||||||
|
"raw": "{\n \"user_id\": \"1\",\n \"old_password\": \"oldpassword123\",\n \"new_password\": \"newpassword123\"\n}"
|
||||||
|
},
|
||||||
|
"url": {
|
||||||
|
"raw": "{{baseUrl}}/auth/change-password",
|
||||||
|
"host": ["{{baseUrl}}"],
|
||||||
|
"path": ["auth", "change-password"]
|
||||||
|
},
|
||||||
|
"description": "用户修改自己的密码（需要提供旧密码）"
|
||||||
|
},
|
||||||
|
"response": [
|
||||||
|
{
|
||||||
|
"name": "密码修改成功",
|
||||||
|
"originalRequest": {
|
||||||
|
"method": "PUT",
|
||||||
|
"header": [
|
||||||
|
{
|
||||||
|
"key": "Content-Type",
|
||||||
|
"value": "application/json"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"body": {
|
||||||
|
"mode": "raw",
|
||||||
|
"raw": "{\n \"user_id\": \"1\",\n \"old_password\": \"oldpassword123\",\n \"new_password\": \"newpassword123\"\n}"
|
||||||
|
},
|
||||||
|
"url": {
|
||||||
|
"raw": "{{baseUrl}}/auth/change-password",
|
||||||
|
"host": ["{{baseUrl}}"],
|
||||||
|
"path": ["auth", "change-password"]
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"status": "OK",
|
||||||
|
"code": 200,
|
||||||
|
"_postman_previewlanguage": "json",
|
||||||
|
"header": [
|
||||||
|
{
|
||||||
|
"key": "Content-Type",
|
||||||
|
"value": "application/json"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"body": "{\n \"success\": true,\n \"message\": \"密码修改成功\"\n}"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
Reference in New Issue
Block a user