docs：更新项目文档结构和说明

- 重新组织docs目录结构 - 在README中添加API文档系统介绍 - 提供Swagger UI快速访问指南 - 完善文档导航和使用说明
2025-12-17 15:16:54 +08:00
parent 1e47c4db60
commit 08bf2bbaf3
2 changed files with 178 additions and 2 deletions
--- a/README.md
+++ b/README.md
@@ -173,10 +173,18 @@ export class PlayerService {
 - [命名规范](./docs/naming_convention.md) - 项目命名规范和最佳实践
 - [NestJS 使用指南](./docs/nestjs_guide.md) - 详细的 NestJS 开发指南，包含实战案例

+### 📖 API 文档
+- **[API 文档总览](./docs/api/README.md)** - API 文档使用指南和快速开始
+- **[Swagger UI](http://localhost:3000/api-docs)** - 交互式 API 文档（需启动服务器）
+- [详细接口文档](./docs/api/api-documentation.md) - 完整的 API 接口说明
+- [OpenAPI 规范](./docs/api/openapi.yaml) - 标准化的 API 描述文件
+- [Postman 集合](./docs/api/postman-collection.json) - 可导入的 API 测试集合
+
 ### 💡 使用建议
 1. **开发前**：先读 AI 辅助指南，了解如何用 AI 帮助遵循规范
 2. **开发中**：参考具体规范文档，使用 AI 实时检查代码质量
-3. **提交前**：用 AI 检查代码和提交信息是否符合规范
+3. **API 开发**：使用 Swagger UI 进行接口测试，参考 API 文档进行开发
+4. **提交前**：用 AI 检查代码和提交信息是否符合规范

 ## 前置要求

@@ -262,10 +270,19 @@ test/
 ├── api/              # API 测试
 └── service/          # 服务测试
 docs/                 # 项目文档
+├── api/                         # API 接口文档
+│   ├── README.md               # API 文档使用指南
+│   ├── api-documentation.md    # 详细接口文档
+│   ├── openapi.yaml           # OpenAPI 规范文件
+│   └── postman-collection.json # Postman 测试集合
+├── systems/                     # 系统设计文档
+│   ├── logger/                 # 日志系统文档
+│   └── user-auth/             # 用户认证系统文档
 ├── backend_development_guide.md  # 后端开发规范
 ├── git_commit_guide.md          # Git 提交规范
 ├── naming_convention.md         # 命名规范
-└── nestjs_guide.md             # NestJS 使用指南
+├── nestjs_guide.md             # NestJS 使用指南
+└── AI辅助开发规范指南.md        # AI 辅助开发指南
 ```

 ## 核心功能
@@ -282,6 +299,26 @@ docs/                 # 项目文档

 **详细文档**: [用户认证系统文档](./docs/systems/user-auth/README.md)

+### 📖 API 文档系统
+
+集成了完整的 API 文档解决方案，提供多种格式的接口文档：
+
+- **Swagger UI** - 交互式 API 文档界面
+- **OpenAPI 规范** - 标准化的 API 描述文件
+- **Postman 集合** - 可导入的 API 测试集合
+- **详细文档** - 包含示例和最佳实践的完整说明
+
+**快速访问**:
+```bash
+# 启动服务器
+pnpm run dev
+
+# 访问 Swagger UI 文档
+# 浏览器打开: http://localhost:3000/api-docs
+```
+
+**详细文档**: [API 文档说明](./docs/api/README.md)
+
 ### 📊 日志系统

 基于 Pino 的高性能日志系统，提供结构化日志记录：
--- a/docs/README.md
+++ b/docs/README.md
@@ -0,0 +1,139 @@
+# 项目文档
+
+本目录包含了像素游戏服务器的完整文档。
+
+## 文档结构
+
+### 📁 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文档
+
+```bash
+# 启动开发服务器
+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](https://editor.swagger.io/)
+2. 将 `docs/openapi.yaml` 的内容复制粘贴到编辑器中
+3. 即可查看可视化的API文档
+
+#### 生成客户端SDK
+```bash
+# 使用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测试登录接口
+
+```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/)