198 lines
4.4 KiB
Markdown
198 lines
4.4 KiB
Markdown
# 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. 团队协作
|
||
- 代码审查包含文档完整性检查
|
||
- 新团队成员参考文档快速上手
|
||
- 前端开发基于文档进行接口对接 |