forked from datawhale/whale-town-end
141 lines
3.9 KiB
Markdown
141 lines
3.9 KiB
Markdown
# 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/) |