whale-town-end/docs

项目文档

本目录包含了像素游戏服务器的完整文档。

文档结构

📁 api/

API接口相关文档，包含：

• api-documentation.md - 详细的API接口文档
• openapi.yaml - OpenAPI 3.0规范文件
• postman-collection.json - Postman测试集合
• README.md - API文档使用说明

📁 systems/

系统设计文档，包含：

• logger/ - 日志系统文档
• user-auth/ - 用户认证系统文档

📄 其他文档

• AI辅助开发规范指南.md - AI开发规范
• backend_development_guide.md - 后端开发指南
• git_commit_guide.md - Git提交规范
• naming_convention.md - 命名规范
• nestjs_guide.md - NestJS开发指南
• 日志系统详细说明.md - 日志系统说明

如何使用

1. 启动服务器并查看Swagger文档

# 启动开发服务器
pnpm run dev

# 访问Swagger UI
# 浏览器打开: http://localhost:3000/api-docs

2. 使用Postman测试API

1. 打开Postman
2. 点击 Import 按钮
3. 选择 docs/postman-collection.json 文件
4. 导入后即可看到所有API接口
5. 修改环境变量 baseUrl 为你的服务器地址（默认：http://localhost:3000）

3. 使用OpenAPI规范

在Swagger Editor中查看

1. 访问 Swagger Editor
2. 将 docs/openapi.yaml 的内容复制粘贴到编辑器中
3. 即可查看可视化的API文档

生成客户端SDK

# 使用swagger-codegen生成JavaScript客户端
swagger-codegen generate -i docs/openapi.yaml -l javascript -o ./client-sdk

# 使用openapi-generator生成TypeScript客户端
openapi-generator generate -i docs/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测试登录接口

# 测试用户登录
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测试

// 用户登录
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文档
• OpenAPI规范
• Postman文档
• Swagger Editor