# API 文档配置指南

## 概览

本项目使用 Swagger/OpenAPI 3.0 规范生成完整的 API 文档，支持在线测试和接口调试。

## 访问文档

启动项目后，可通过以下地址访问API文档：

- **交互式文档**: http://localhost:3000/api/docs
- **JSON格式**: http://localhost:3000/api/docs-json
- **YAML格式**: http://localhost:3000/api/docs-yaml

## 文档配置

### 1. 主配置文件

文件位置: `src/config/swagger.config.ts`

包含以下配置：
- API基础信息（标题、描述、版本）
- JWT认证配置
- 标签分类
- 多环境服务器配置
- UI自定义选项

### 2. DTO文档化

#### 通用响应格式
- `src/dto/common-response.dto.ts` - 统一响应格式
- `src/dto/error-response.dto.ts` - 错误响应格式

#### 模板系统DTO
- `src/dto/template.dto.ts` - 模板相关数据传输对象
  - `CreateTemplateDto` - 创建模板
  - `UpdateTemplateDto` - 更新模板
  - `TemplateExecuteDto` - 执行模板
  - `TemplateListDto` - 模板列表
  - `BatchExecuteDto` - 批量执行

#### 平台用户DTO
- `src/platform/dto/platform-login.dto.ts` - 平台登录相关

### 3. Controller文档化

#### 装饰器使用
```typescript
@ApiTags('功能模块') // 分组标签
@ApiOperation({ summary: '接口摘要', description: '详细描述' })
@ApiResponse({ status: 200, description: '成功', type: ResponseDto })
@ApiParam({ name: 'id', description: '参数描述' })
@ApiQuery({ name: 'filter', required: false })
@ApiBody({ type: RequestDto })
@ApiBearerAuth('JWT-auth') // JWT认证
```

#### 通用装饰器
- `src/decorators/api-common-responses.decorator.ts`
  - `@ApiCommonResponses()` - 通用错误响应
  - `@ApiAuthResponses()` - 认证相关错误

## 支持的功能模块

### 1. 用户管理 (`用户管理`)
- 多平台统一登录
- 用户信息获取与更新
- 平台账号绑定/解绑
- 支持的平台列表查询

### 2. AI模板系统 (`AI模板系统`)
- 模板列表查询（支持类型筛选）
- 模板详情获取
- 模板执行（单个/批量）
- 模板推荐
- 模板管理（创建/更新/删除）

### 3. 平台适配 (`平台适配`)
- 各平台特定接口
- 数据同步功能

### 4. 积分系统 (`积分系统`)
- 积分获取、消耗、查询管理

### 5. 扩展服务 (`扩展服务`)
- 预留的扩展功能接口

## API 规范

### 统一响应格式

```json
{
  "code": 200,
  "message": "success",
  "data": {},
  "timestamp": 1703001000000,
  "traceId": "trace-uuid"
}
```

### 错误码规范

- **1000-1999**: 系统级错误
- **2000-2999**: 业务级错误  
- **3000-3999**: 平台特定错误
- **4000-4999**: 客户端错误
- **5000-5999**: 服务端错误

### 认证方式

使用 JWT Bearer Token 进行接口认证：

```bash
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

## 开发指南

### 1. 添加新接口文档

1. **创建DTO类**：
```typescript
export class NewFeatureDto {
  @ApiProperty({ description: '字段描述', example: '示例值' })
  @IsString()
  field: string;
}
```

2. **Controller添加装饰器**：
```typescript
@ApiTags('功能模块')
@ApiCommonResponses()
export class NewController {
  @Post()
  @ApiOperation({ summary: '接口摘要', description: '详细描述' })
  @ApiBody({ type: NewFeatureDto })
  @ApiResponse({ status: 200, description: '成功' })
  async newEndpoint() {}
}
```

### 2. 生成静态文档

```bash
# 生成 Swagger JSON 文档
npm run docs:generate

# 启动文档服务
npm run docs:serve
```

### 3. 文档验证

启动项目后访问 http://localhost:3000/api/docs 验证：
- 接口分组是否正确
- 参数描述是否完整
- 响应格式是否标准
- 认证配置是否生效

## 部署注意事项

### 生产环境配置

生产环境默认禁用 Swagger 文档，确保安全性：

```typescript
// 仅在非生产环境启用 Swagger
if (process.env.NODE_ENV !== 'production') {
  setupSwagger(app);
}
```

### 自定义域名配置

需要在 `swagger.config.ts` 中更新服务器配置：

```typescript
.addServer('https://your-domain.com', '生产环境')
```

## 维护指南

### 1. 定期更新
- 新增接口后及时添加文档
- 保持DTO和实际接口同步
- 更新示例数据和错误信息

### 2. 版本管理
- API版本变更时更新文档版本号
- 重要变更添加changelog说明
- 保持向后兼容性文档说明

### 3. 团队协作
- 代码审查包含文档完整性检查
- 新团队成员参考文档快速上手
- 前端开发基于文档进行接口对接