4.4 KiB

Raw Permalink Blame History

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文档化

装饰器使用

@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 规范

统一响应格式

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

错误码规范

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

认证方式

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

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

开发指南

1. 添加新接口文档

创建DTO类：

export class NewFeatureDto {
  @ApiProperty({ description: '字段描述', example: '示例值' })
  @IsString()
  field: string;
}

Controller添加装饰器：

@ApiTags('功能模块')
@ApiCommonResponses()
export class NewController {
  @Post()
  @ApiOperation({ summary: '接口摘要', description: '详细描述' })
  @ApiBody({ type: NewFeatureDto })
  @ApiResponse({ status: 200, description: '成功' })
  async newEndpoint() {}
}

2. 生成静态文档

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

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

3. 文档验证

启动项目后访问 http://localhost:3000/api/docs 验证：

接口分组是否正确
参数描述是否完整
响应格式是否标准
认证配置是否生效

部署注意事项

生产环境配置

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

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

自定义域名配置

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

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

维护指南

1. 定期更新

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

2. 版本管理

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

3. 团队协作

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

4.4 KiB Raw Permalink Blame History Unescape Escape