create-dp-koa 1.0.0

package/template/docs/SWAGGER_INTEGRATION_GUIDE.md

@@ -0,0 +1,416 @@
+# Swagger 集成使用指南
+
+## 概述
+
+本文档介绍如何在 DP Koa Framework 中使用 Swagger 注解来生成 API 文档。
+
+## 功能特性
+
+- ✅ **注解式文档生成**：通过装饰器生成 Swagger 文档
+- ✅ **自动生成 UI**：提供 Swagger UI 界面查看和测试 API
+- ✅ **开发环境专用**：仅在开发环境下启用
+- ✅ **类型安全**：支持 TypeScript 类型提示
+
+## 快速开始
+
+### 1. 访问 Swagger UI
+
+启动应用后，访问以下地址：
+
+- **Swagger UI**：http://localhost:3000/swagger
+- **Swagger JSON**：http://localhost:3000/swagger.json
+
+### 2. 基础用法
+
+#### 类级别注解
+
+使用 `@ApiTags` 为 Controller 类添加标签：
+
+```typescript
+import { ApiTags } from '@src/framework/decorator/swagger';
+
+@ApiTags('用户管理', '用户相关接口')
+export class UserController extends BaseController {
+    // ...
+}
+```
+
+#### 方法级别注解
+
+使用 `@Api` 为方法添加基本信息：
+
+```typescript
+import { Api } from '@src/framework/decorator/swagger';
+
+@Get('/user')
+@Api({
+    tags: ['用户管理'],
+    summary: '获取用户列表',
+    description: '根据查询参数获取用户列表',
+    operationId: 'getUserList',
+})
+async getUserList() {
+    // ...
+}
+```
+
+#### 响应注解
+
+使用 `@ApiResponse` 定义响应结构：
+
+```typescript
+import { ApiResponse } from '@src/framework/decorator/swagger';
+
+@ApiResponse({
+    status: 200,
+    description: '成功返回用户列表',
+    schema: {
+        type: 'object',
+        properties: {
+            code: { type: 'number' },
+            data: { type: 'array' },
+            message: { type: 'string' },
+        },
+    },
+})
+```
+
+## 完整示例
+
+### 1. GET 请求示例
+
+```typescript
+import { Get, Query } from '@src/framework/decorator/controller';
+import { Api, ApiResponse } from '@src/framework/decorator/swagger';
+
+@Api({
+    tags: ['用户管理'],
+    summary: '获取用户列表',
+    description: '根据查询参数获取用户列表',
+})
+@ApiResponse({
+    status: 200,
+    description: '成功返回用户列表',
+})
+@ApiResponse({
+    status: 400,
+    description: '参数错误',
+})
+@Get('/user/list')
+async getUserList(@Query() query: { page: number; pageSize: number }) {
+    return this.success({
+        users: [],
+        total: 0,
+    });
+}
+```
+
+### 2. POST 请求示例
+
+```typescript
+import { Post, Body } from '@src/framework/decorator/controller';
+import { Api, ApiBody, ApiResponse } from '@src/framework/decorator/swagger';
+
+@Api({
+    tags: ['用户管理'],
+    summary: '创建用户',
+    description: '创建新用户',
+})
+@ApiBody({
+    description: '用户信息',
+    required: true,
+    schema: {
+        type: 'object',
+        required: ['name', 'email'],
+        properties: {
+            name: { type: 'string' },
+            email: { type: 'string', format: 'email' },
+            age: { type: 'number' },
+        },
+    },
+})
+@ApiResponse({
+    status: 200,
+    description: '成功创建用户',
+})
+@Post('/user')
+async createUser(@Body() body: { name: string; email: string; age?: number }) {
+    return this.success({ id: 1, ...body });
+}
+```
+
+### 3. 带路径参数的示例
+
+```typescript
+import { Get, Params } from '@src/framework/decorator/controller';
+import { Api, ApiResponse } from '@src/framework/decorator/swagger';
+
+@Api({
+    tags: ['用户管理'],
+    summary: '获取用户详情',
+    description: '根据用户ID获取用户信息',
+})
+@ApiResponse({
+    status: 200,
+    description: '成功返回用户详情',
+})
+@ApiResponse({
+    status: 404,
+    description: '用户不存在',
+})
+@Get('/user/:id')
+async getUserById(@Params() params: { id: number }) {
+    return this.success({ id: params.id, name: '张三' });
+}
+```
+
+## 装饰器说明
+
+### @ApiTags
+
+为类添加标签，用于分组。
+
+```typescript
+@ApiTags('用户管理', '示例')
+```
+
+### @Api
+
+为方法添加基本信息。
+
+```typescript
+@Api({
+    tags?: string[];        // 标签
+    summary?: string;        // 摘要
+    description?: string;    // 详细描述
+    operationId?: string;   // 操作ID
+})
+```
+
+### @ApiResponse
+
+定义 API 响应结构。
+
+```typescript
+@ApiResponse({
+    status: number;          // HTTP 状态码
+    description: string;     // 响应描述
+    schema?: any;           // 响应 schema
+    examples?: Record<string, any>;  // 示例数据
+})
+```
+
+### @ApiBody
+
+定义请求体结构。
+
+```typescript
+@ApiBody({
+    description?: string;    // 描述
+    required?: boolean;      // 是否必需
+    schema: any;            // Schema
+    examples?: Record<string, any>;  // 示例数据
+})
+```
+
+### @ApiParam
+
+定义路径参数。
+
+```typescript
+@ApiParam({
+    name: string;            // 参数名
+    in: 'path' | 'query' | 'header' | 'cookie';
+    description?: string;   // 描述
+    required?: boolean;      // 是否必需
+    schema?: any;          // Schema
+    example?: any;         // 示例
+})
+```
+
+## 响应 Schema 定义
+
+### 基础类型
+
+```typescript
+{
+    type: 'string',
+    type: 'number',
+    type: 'boolean',
+    type: 'integer',
+}
+```
+
+### 对象类型
+
+```typescript
+{
+    type: 'object',
+    properties: {
+        name: { type: 'string' },
+        age: { type: 'number' },
+    },
+    required: ['name'],  // 必需字段
+}
+```
+
+### 数组类型
+
+```typescript
+{
+    type: 'array',
+    items: {
+        type: 'string',
+    },
+}
+```
+
+### 复杂对象
+
+```typescript
+{
+    type: 'object',
+    properties: {
+        code: { type: 'number', example: 0 },
+        data: {
+            type: 'array',
+            items: {
+                type: 'object',
+                properties: {
+                    id: { type: 'number' },
+                    name: { type: 'string' },
+                },
+            },
+        },
+        message: { type: 'string' },
+    },
+}
+```
+
+## 最佳实践
+
+### 1. 统一响应格式
+
+定义统一的响应格式：
+
+```typescript
+@ApiResponse({
+    status: 200,
+    description: '成功响应',
+    schema: {
+        type: 'object',
+        properties: {
+            code: { type: 'number', example: 0 },
+            data: { type: 'object' },
+            message: { type: 'string', example: '操作成功' },
+        },
+    },
+})
+```
+
+### 2. 错误响应
+
+为所有接口定义错误响应：
+
+```typescript
+@ApiResponse({
+    status: 400,
+    description: '参数错误',
+})
+@ApiResponse({
+    status: 401,
+    description: '未授权',
+})
+@ApiResponse({
+    status: 403,
+    description: '权限不足',
+})
+@ApiResponse({
+    status: 500,
+    description: '服务器错误',
+})
+```
+
+### 3. 使用标签分组
+
+使用 `@ApiTags` 对 API 进行分组：
+
+```typescript
+@ApiTags('用户管理')
+@ApiTags('订单管理')
+@ApiTags('商品管理')
+```
+
+### 4. 提供完整示例
+
+为复杂的数据结构提供示例：
+
+```typescript
+@ApiBody({
+    schema: {
+        type: 'object',
+        properties: {
+            name: { type: 'string' },
+            email: { type: 'string' },
+        },
+    },
+    examples: {
+        example1: {
+            summary: '示例数据',
+            value: {
+                name: '张三',
+                email: 'zhang@example.com',
+            },
+        },
+    },
+})
+```
+
+## 查看示例
+
+项目提供了完整的示例：
+
+1. **基础示例**：`src/controllers/example/ExampleController.ts`
+2. **完整示例**：`src/controllers/example/SwaggerExampleController.ts`
+
+启动应用后，访问以下地址查看：
+
+- http://localhost:3000/swagger
+- http://localhost:3000/swagger/user/list (GET)
+- http://localhost:3000/swagger/user/:id (GET)
+- http://localhost:3000/swagger/user (POST)
+- http://localhost:3000/swagger/user/:id (PUT)
+- http://localhost:3000/swagger/user/:id (DELETE)
+
+## 注意事项
+
+1. **仅开发环境**：Swagger UI 仅在开发环境下启用
+2. **类型安全**：建议为 DTO 类添加类验证器
+3. **完整描述**：为所有接口提供完整的描述和示例
+4. **统一格式**：保持响应格式的一致性
+5. **版本控制**：在生产环境中关闭 Swagger 访问
+
+## 故障排查
+
+### 问题1：无法访问 Swagger UI
+
+**解决方案**：
+- 确认环境变量 `NODE_ENV` 不是 `production`
+- 检查端口是否正确
+- 查看控制台是否有错误信息
+
+### 问题2：文档不完整
+
+**解决方案**：
+- 检查是否添加了必要的装饰器
+- 确认路由已正确注册
+- 查看生成的 JSON 文件
+
+## 扩展阅读
+
+- [Swagger OpenAPI 规范](https://swagger.io/specification/)
+- [koa2-swagger-ui 文档](https://www.npmjs.com/package/koa2-swagger-ui)
+- [swagger-jsdoc 文档](https://github.com/Surnet/swagger-jsdoc)
+
+
+