📝 docs: 파일 업로드 API Swagger 문서 작성

Author: asn6878

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';
     CommentModule,
     MetricsModule,
     LikeModule,
+    FileModule,
   ],
   controllers: [],
   providers: [

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();
 

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: '인증이 필요합니다.',
+          },
+        },
+      },
+    }),
+  );
+}

server/src/file/api-docs/uploadProfileFile.api-docs.ts

@@ -0,0 +1,100 @@
+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: {
+              resultFile: {
+                type: 'object',
+                properties: {
+                  id: {
+                    type: 'string',
+                    example: 'uuid-string',
+                  },
+                  filename: {
+                    type: 'string',
+                    example: 'profile-image.jpg',
+                  },
+                  originalName: {
+                    type: 'string',
+                    example: 'my-photo.jpg',
+                  },
+                  mimeType: {
+                    type: 'string',
+                    example: 'image/jpeg',
+                  },
+                  size: {
+                    type: 'number',
+                    example: 1024000,
+                  },
+                  path: {
+                    type: 'string',
+                    example: '/uploads/profile/uuid-string.jpg',
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    }),
+    ApiBadRequestResponse({
+      description: '잘못된 요청',
+      schema: {
+        properties: {
+          message: {
+            type: 'string',
+            example: '파일이 선택되지 않았습니다.',
+          },
+        },
+      },
+    }),
+    ApiUnauthorizedResponse({
+      description: '인증되지 않은 사용자',
+      schema: {
+        properties: {
+          message: {
+            type: 'string',
+            example: '인증이 필요합니다.',
+          },
+        },
+      },
+    }),
+  );
+}

server/src/file/controller/file.controller.ts

@@ -16,13 +16,16 @@ 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';
 @ApiTags('File')
 @Controller('file')
 @UseGuards(JwtGuard)
 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) {
@@ -41,6 +44,7 @@ export class FileController {
 
   // TODO: 권한검사 추가
   @Delete(':id')
+  @ApiDeleteFile()
   async deleteFile(@Param('id') id: string, @Req() req) {
     await this.fileService.deleteFile(id);
     return { message: '파일이 성공적으로 삭제되었습니다.' };