From 1e47c4db60294e44ca312e7782e66ec3b25ca39b Mon Sep 17 00:00:00 2001 From: moyin <244344649@qq.com> Date: Wed, 17 Dec 2025 15:16:27 +0800 Subject: [PATCH] =?UTF-8?q?docs=EF=BC=9A=E5=88=9B=E5=BB=BA=E5=AE=8C?= =?UTF-8?q?=E6=95=B4=E7=9A=84API=E6=8E=A5=E5=8F=A3=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 创建详细的API接口说明文档 - 提供OpenAPI 3.0规范文件 - 创建Postman测试集合 - 添加API文档使用指南 --- docs/api/README.md | 141 ++++++++ docs/api/api-documentation.md | 412 ++++++++++++++++++++++ docs/api/openapi.yaml | 568 +++++++++++++++++++++++++++++++ docs/api/postman-collection.json | 347 +++++++++++++++++++ 4 files changed, 1468 insertions(+) create mode 100644 docs/api/README.md create mode 100644 docs/api/api-documentation.md create mode 100644 docs/api/openapi.yaml create mode 100644 docs/api/postman-collection.json diff --git a/docs/api/README.md b/docs/api/README.md new file mode 100644 index 0000000..13caac1 --- /dev/null +++ b/docs/api/README.md @@ -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/) \ No newline at end of file diff --git a/docs/api/api-documentation.md b/docs/api/api-documentation.md new file mode 100644 index 0000000..3c5199d --- /dev/null +++ b/docs/api/api-documentation.md @@ -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): 初始版本，包含基础的用户认证功能 \ No newline at end of file diff --git a/docs/api/openapi.yaml b/docs/api/openapi.yaml new file mode 100644 index 0000000..7151c11 --- /dev/null +++ b/docs/api/openapi.yaml @@ -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 \ No newline at end of file diff --git a/docs/api/postman-collection.json b/docs/api/postman-collection.json new file mode 100644 index 0000000..b7b9dfa --- /dev/null +++ b/docs/api/postman-collection.json @@ -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}" + } + ] + } + ] +} \ No newline at end of file