feat: add Swagger API documentation for video media management endpoints

apps/box-mgnt-api/src/mgnt-backend/feature/video-media/video-media.controller.ts

@@ -11,6 +11,14 @@ import {
   UploadedFile,
 } from '@nestjs/common';
 import { FileInterceptor } from '@nestjs/platform-express';
+import {
+  ApiTags,
+  ApiOperation,
+  ApiParam,
+  ApiConsumes,
+  ApiBody,
+  ApiResponse,
+} from '@nestjs/swagger';
 import { VideoMediaService } from './video-media.service';
 import {
   VideoMediaListQueryDto,
@@ -19,6 +27,7 @@ import {
   BatchUpdateVideoMediaStatusDto,
 } from './video-media.dto';
 
+@ApiTags('视频管理')
 @Controller('video-media')
 export class VideoMediaController {
   constructor(private readonly videoMediaService: VideoMediaService) {}
@@ -27,6 +36,11 @@ export class VideoMediaController {
    * 列表查询
    * GET /video-media
    */
+  @ApiOperation({
+    summary: '获取视频媒体列表',
+    description: '支持分页、关键词搜索、分类和标签过滤',
+  })
+  @ApiResponse({ status: 200, description: '返回视频媒体列表' })
   @Post('list')
   async findAll(@Query() query: VideoMediaListQueryDto) {
     return this.videoMediaService.findAll(query);
@@ -36,6 +50,13 @@ export class VideoMediaController {
    * 详情（管理弹窗）
    * GET /video-media/:id
    */
+  @ApiOperation({
+    summary: '获取视频媒体详情',
+    description: '获取单个视频媒体的详细信息',
+  })
+  @ApiParam({ name: 'id', description: '视频媒体ID', type: String })
+  @ApiResponse({ status: 200, description: '返回视频媒体详情' })
+  @ApiResponse({ status: 404, description: '视频媒体不存在' })
   @Get(':id')
   async findOne(@Param('id') id: string) {
     return this.videoMediaService.findOne(id);
@@ -45,6 +66,13 @@ export class VideoMediaController {
    * 管理弹窗保存（标题 / 分类 / 标签 / 上下架）
    * PATCH /video-media/:id/manage
    */
+  @ApiOperation({
+    summary: '更新视频媒体管理信息',
+    description: '更新标题、分类、标签、上下架状态等信息',
+  })
+  @ApiParam({ name: 'id', description: '视频媒体ID', type: String })
+  @ApiResponse({ status: 200, description: '更新成功' })
+  @ApiResponse({ status: 404, description: '视频媒体不存在' })
   @Patch(':id/manage')
   async updateManage(
     @Param('id') id: string,
@@ -57,6 +85,13 @@ export class VideoMediaController {
    * 单个上/下架
    * PATCH /video-media/:id/status
    */
+  @ApiOperation({
+    summary: '更新视频媒体上下架状态',
+    description: '单个视频的上架或下架操作',
+  })
+  @ApiParam({ name: 'id', description: '视频媒体ID', type: String })
+  @ApiResponse({ status: 200, description: '状态更新成功' })
+  @ApiResponse({ status: 404, description: '视频媒体不存在' })
   @Patch(':id/status')
   async updateStatus(
     @Param('id') id: string,
@@ -69,6 +104,11 @@ export class VideoMediaController {
    * 批量上/下架
    * POST /video-media/batch/status
    */
+  @ApiOperation({
+    summary: '批量更新视频媒体上下架状态',
+    description: '批量对多个视频进行上架或下架操作',
+  })
+  @ApiResponse({ status: 200, description: '批量更新成功' })
   @Post('batch/status')
   async batchUpdateStatus(@Body() dto: BatchUpdateVideoMediaStatusDto) {
     return this.videoMediaService.batchUpdateStatus(dto);
@@ -80,6 +120,26 @@ export class VideoMediaController {
    * - 这里示例使用 FileInterceptor；实际中你会上传到 S3，得到一个 URL / key
    * POST /video-media/:id/cover
    */
+  @ApiOperation({
+    summary: '上传视频封面',
+    description: '为指定视频上传自定义封面图片',
+  })
+  @ApiParam({ name: 'id', description: '视频媒体ID', type: String })
+  @ApiConsumes('multipart/form-data')
+  @ApiBody({
+    description: '封面图片文件',
+    schema: {
+      type: 'object',
+      properties: {
+        file: {
+          type: 'string',
+          format: 'binary',
+        },
+      },
+    },
+  })
+  @ApiResponse({ status: 200, description: '封面上传成功' })
+  @ApiResponse({ status: 404, description: '视频媒体不存在' })
   @Post(':id/cover')
   @UseInterceptors(FileInterceptor('file'))
   async updateCover(