21a2865e43
- 集成Swagger文档生成和UI界面 - 为所有API端点添加详细的文档注解 - 添加统一的响应装饰器和DTO类型定义 - 优化API路由结构和全局验证配置 - 新增文档生成和服务脚本命令
79 lines
2.7 KiB
TypeScript
79 lines
2.7 KiB
TypeScript
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
|
||
import { INestApplication } from '@nestjs/common';
|
||
|
||
export function setupSwagger(app: INestApplication): void {
|
||
const config = new DocumentBuilder()
|
||
.setTitle('多平台小程序统一后台API')
|
||
.setDescription(`
|
||
## 功能特性
|
||
- 🔐 统一用户认证 (微信/支付宝/百度/字节跳动等)
|
||
- 🎨 AI模板系统 (图片/视频生成)
|
||
- 💰 积分系统 (积分获取、消耗、管理)
|
||
- 📱 多平台适配 (8大平台支持)
|
||
- 🧩 扩展数据存储 (灵活的JSON数据)
|
||
|
||
## 认证方式
|
||
使用JWT Bearer Token进行API认证
|
||
|
||
## 响应格式
|
||
所有API响应都遵循统一格式：
|
||
\`\`\`json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {},
|
||
"timestamp": 1703001000000,
|
||
"traceId": "trace-uuid"
|
||
}
|
||
\`\`\`
|
||
`)
|
||
.setVersion('1.0.0')
|
||
.setContact('开发团队', 'https://example.com', 'dev@example.com')
|
||
.setLicense('MIT', 'https://opensource.org/licenses/MIT')
|
||
.addBearerAuth(
|
||
{
|
||
type: 'http',
|
||
scheme: 'bearer',
|
||
bearerFormat: 'JWT',
|
||
name: 'JWT',
|
||
description: 'Enter JWT token',
|
||
in: 'header',
|
||
},
|
||
'JWT-auth',
|
||
)
|
||
.addTag('用户管理', '用户注册、登录、信息管理')
|
||
.addTag('平台适配', '各平台特定接口和数据同步')
|
||
.addTag('AI模板系统', 'AI图片/视频生成模板管理')
|
||
.addTag('积分系统', '积分获取、消耗、查询管理')
|
||
.addTag('扩展服务', '预留的扩展功能接口')
|
||
.addServer('http://localhost:3000', '开发环境')
|
||
.addServer('https://api-dev.example.com', '测试环境')
|
||
.addServer('https://api.example.com', '生产环境')
|
||
.build();
|
||
|
||
const document = SwaggerModule.createDocument(app as any, config, {
|
||
operationIdFactory: (controllerKey: string, methodKey: string) => methodKey,
|
||
});
|
||
|
||
console.log('🔧 Setting up Swagger documentation...');
|
||
SwaggerModule.setup('docs', app as any, document, {
|
||
swaggerOptions: {
|
||
persistAuthorization: true,
|
||
tagsSorter: 'alpha',
|
||
operationsSorter: 'alpha',
|
||
docExpansion: 'none',
|
||
filter: true,
|
||
showRequestDuration: true,
|
||
},
|
||
customSiteTitle: '多平台API文档',
|
||
customfavIcon: '/favicon.ico',
|
||
customJs: [
|
||
'https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/4.15.5/swagger-ui-bundle.min.js',
|
||
'https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/4.15.5/swagger-ui-standalone-preset.min.js',
|
||
],
|
||
customCssUrl: [
|
||
'https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/4.15.5/swagger-ui.min.css',
|
||
],
|
||
});
|
||
console.log('✅ Swagger documentation setup completed at /api/docs');
|
||
} |