Merge pull request #449 from boostcampwm-2024/docs/file-upload

asn6878 · web-flow · commit 0ad4b9d7c317 · 2025-08-11T10:57:54.000+09:00
📝 docs: 파일 업로드 API Swagger 작성
diff --git a/server/src/app.module.ts b/server/src/app.module.ts
@@ -18,6 +18,7 @@ import { MetricsModule } from './common/metrics/metrics.module';
 import { APP_INTERCEPTOR } from '@nestjs/core';
 import { MetricsInterceptor } from './common/metrics/metrics.interceptor';
 import { LikeModule } from './like/module/like.module';
+import { FileModule } from './file/module/file.module';
 
 @Module({
   imports: [
@@ -50,6 +51,7 @@ import { LikeModule } from './like/module/like.module';
     StatisticModule,
     CommentModule,
     LikeModule,
+    FileModule,
   ],
   controllers: [],
   providers: [
diff --git a/server/src/common/swagger/swagger.ts b/server/src/common/swagger/swagger.ts
@@ -16,6 +16,7 @@ export function setupSwagger(app: INestApplication) {
     .addTag('Statistic', '통계 정보 조회 API')
     .addTag('User', '사용자 관리와 인증 관련 API')
     .addTag('OAuth', 'OAuth 관련 API')
+    .addTag('File', '파일 업로드 및 관리 API')
     .setLicense('MIT License', 'https://opensource.org/licenses/MIT')
     .build();
 
diff --git a/server/src/file/api-docs/deleteFile.api-docs.ts b/server/src/file/api-docs/deleteFile.api-docs.ts
@@ -0,0 +1,68 @@
+import { applyDecorators } from '@nestjs/common';
+import {
+  ApiBadRequestResponse,
+  ApiNotFoundResponse,
+  ApiOkResponse,
+  ApiOperation,
+  ApiParam,
+  ApiUnauthorizedResponse,
+} from '@nestjs/swagger';
+
+export function ApiDeleteFile() {
+  return applyDecorators(
+    ApiOperation({
+      summary: '파일 삭제 API',
+      description: '업로드된 파일을 삭제합니다.',
+    }),
+    ApiParam({
+      name: 'id',
+      description: '삭제할 파일의 ID',
+      type: 'string',
+      example: 'uuid-string',
+    }),
+    ApiOkResponse({
+      description: '파일 삭제 성공',
+      schema: {
+        properties: {
+          message: {
+            type: 'string',
+            example: '파일이 성공적으로 삭제되었습니다.',
+          },
+        },
+      },
+    }),
+    ApiBadRequestResponse({
+      description: '잘못된 요청',
+      schema: {
+        properties: {
+          message: {
+            type: 'string',
+            example: '유효하지 않은 파일 ID입니다.',
+          },
+        },
+      },
+    }),
+    ApiNotFoundResponse({
+      description: '파일을 찾을 수 없음',
+      schema: {
+        properties: {
+          message: {
+            type: 'string',
+            example: '파일을 찾을 수 없습니다.',
+          },
+        },
+      },
+    }),
+    ApiUnauthorizedResponse({
+      description: '인증되지 않은 사용자',
+      schema: {
+        properties: {
+          message: {
+            type: 'string',
+            example: '인증이 필요합니다.',
+          },
+        },
+      },
+    }),
+  );
+}
diff --git a/server/src/file/api-docs/uploadProfileFile.api-docs.ts b/server/src/file/api-docs/uploadProfileFile.api-docs.ts
@@ -0,0 +1,107 @@
+import { applyDecorators } from '@nestjs/common';
+import {
+  ApiBadRequestResponse,
+  ApiBody,
+  ApiConsumes,
+  ApiOkResponse,
+  ApiOperation,
+  ApiUnauthorizedResponse,
+} from '@nestjs/swagger';
+
+export function ApiUploadProfileFile() {
+  return applyDecorators(
+    ApiOperation({
+      summary: '프로필 이미지 업로드 API',
+      description: '사용자의 프로필 이미지를 업로드합니다.',
+    }),
+    ApiConsumes('multipart/form-data'),
+    ApiBody({
+      description: '업로드할 파일',
+      schema: {
+        type: 'object',
+        properties: {
+          file: {
+            type: 'string',
+            format: 'binary',
+            description: '업로드할 이미지 파일 (JPG, PNG, GIF 등)',
+          },
+        },
+        required: ['file'],
+      },
+    }),
+    ApiOkResponse({
+      description: '파일 업로드 성공',
+      schema: {
+        properties: {
+          message: {
+            type: 'string',
+            example: '파일 업로드에 성공했습니다.',
+          },
+          data: {
+            type: 'object',
+            properties: {
+              id: {
+                type: 'number',
+                example: 1,
+                description: '파일 ID',
+              },
+              originalName: {
+                type: 'string',
+                example: 'my-photo.jpg',
+                description: '원본 파일명',
+              },
+              mimetype: {
+                type: 'string',
+                example: 'image/jpeg',
+                description: '파일 MIME Type',
+              },
+              size: {
+                type: 'number',
+                example: 1024000,
+                description: '파일 크기 (bytes)',
+              },
+              url: {
+                type: 'string',
+                example: '/objects/profile/2024/01/profile-image.jpg',
+                description: '파일 접근 URL',
+              },
+              userId: {
+                type: 'number',
+                example: 123,
+                description: '업로드한 사용자 ID',
+              },
+              createdAt: {
+                type: 'string',
+                format: 'date-time',
+                example: '2024-01-01T12:00:00.000Z',
+                description: '업로드 날짜',
+              },
+            },
+          },
+        },
+      },
+    }),
+    ApiBadRequestResponse({
+      description: '잘못된 요청',
+      schema: {
+        properties: {
+          message: {
+            type: 'string',
+            example: '파일이 선택되지 않았습니다.',
+          },
+        },
+      },
+    }),
+    ApiUnauthorizedResponse({
+      description: '인증되지 않은 사용자',
+      schema: {
+        properties: {
+          message: {
+            type: 'string',
+            example: '인증이 필요합니다.',
+          },
+        },
+      },
+    }),
+  );
+}
diff --git a/server/src/file/controller/file.controller.ts b/server/src/file/controller/file.controller.ts
@@ -16,6 +16,9 @@ import { ApiTags } from '@nestjs/swagger';
 import { JwtGuard } from '../../common/guard/jwt.guard';
 import { createDynamicStorage } from '../../common/disk/diskStorage';
 import { ApiResponse } from '../../common/response/common.response';
+import { ApiUploadProfileFile } from '../api-docs/uploadProfileFile.api-docs';
+import { ApiDeleteFile } from '../api-docs/deleteFile.api-docs';
+import { FileUploadResponseDto } from '../dto/createFile.dto';
 
 @ApiTags('File')
 @Controller('file')
@@ -24,24 +27,27 @@ export class FileController {
   constructor(private readonly fileService: FileService) {}
 
   @Post('upload/profile')
+  @ApiUploadProfileFile()
   @UseInterceptors(FileInterceptor('file', createDynamicStorage()))
   async upload(@UploadedFile() file: any, @Req() req) {
     if (!file) {
       throw new BadRequestException('파일이 선택되지 않았습니다.');
     }
 
-    const resultFile = await this.fileService.create(
+    const responseDto = await this.fileService.create(
       file,
       Number.parseInt(req.user.id),
     );
 
-    return ApiResponse.responseWithData('파일 업로드에 성공했습니다.', {
-      resultFile,
-    });
+    return ApiResponse.responseWithData(
+      '파일 업로드에 성공했습니다.',
+      responseDto,
+    );
   }
 
   // TODO: 권한검사 추가
   @Delete(':id')
+  @ApiDeleteFile()
   async deleteFile(@Param('id') id: string, @Req() req) {
     const fileId = parseInt(id, 10);
     if (isNaN(fileId)) {
diff --git a/server/src/file/dto/createFile.dto.ts b/server/src/file/dto/createFile.dto.ts
@@ -1,19 +1,24 @@
 import { ApiProperty } from '@nestjs/swagger';
-import { IsOptional, IsString, MaxLength } from 'class-validator';
 
 export class FileUploadResponseDto {
   @ApiProperty({ description: '파일 ID' })
   id: number;
 
-  @ApiProperty({ description: '저장된 파일명' })
-  filename: string;
+  @ApiProperty({ description: '원본 파일명' })
+  originalName: string;
 
   @ApiProperty({ description: '파일 MIME Type' })
-  mimeType: string;
+  mimetype: string;
 
   @ApiProperty({ description: '파일 크기 (bytes)' })
   size: number;
 
+  @ApiProperty({ description: '파일 접근 URL' })
+  url: string;
+
+  @ApiProperty({ description: '업로드한 사용자 ID' })
+  userId: number;
+
   @ApiProperty({ description: '업로드 날짜' })
   createdAt: Date;
 }
diff --git a/server/src/file/service/file.service.ts b/server/src/file/service/file.service.ts
@@ -3,12 +3,13 @@ import { File } from '../entity/file.entity';
 import { unlinkSync, existsSync } from 'fs';
 import { FileRepository } from '../repository/file.repository';
 import { User } from '../../user/entity/user.entity';
+import { FileUploadResponseDto } from '../dto/createFile.dto';
 
 @Injectable()
 export class FileService {
   constructor(private readonly fileRepository: FileRepository) {}
 
-  async create(file: any, userId: number) {
+  async create(file: any, userId: number): Promise<FileUploadResponseDto> {
     const { originalName, mimetype, size, path } = file;
 
     const savedFile = await this.fileRepository.save({
@@ -21,8 +22,13 @@ export class FileService {
     const accessUrl = this.generateAccessUrl(path);
 
     return {
-      ...savedFile,
+      id: savedFile.id,
+      originalName: savedFile.originalName,
+      mimetype: savedFile.mimetype,
+      size: savedFile.size,
       url: accessUrl,
+      userId: userId,
+      createdAt: savedFile.createdAt,
     };
   }
 
