Merge pull request #112 from boostcampwm-2024/feature-be-#106

swagger 적용 완료

Author: ezcolin2

backend/db_name

@@ -25,6 +25,7 @@
     "@nestjs/core": "^10.0.0",
     "@nestjs/mapped-types": "*",
     "@nestjs/platform-express": "^10.0.0",
+    "@nestjs/swagger": "^8.0.5",
     "@nestjs/typeorm": "^10.0.2",
     "class-transformer": "^0.5.1",
     "class-validator": "^0.14.1",

backend/package.json

@@ -1,9 +1,17 @@
 import { NestFactory } from '@nestjs/core';
 import { AppModule } from './app.module';
 import { HttpExceptionFilter } from './filter/http-exception.filter';
+import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';
 
 async function bootstrap() {
   const app = await NestFactory.create(AppModule);
+
+  const config = new DocumentBuilder()
+    .setTitle('OctoDocs')
+    .setDescription('OctoDocs API 명세서')
+    .build();
+  const documentFactory = () => SwaggerModule.createDocument(app, config);
+  SwaggerModule.setup('api', app, documentFactory);
   app.useGlobalFilters(new HttpExceptionFilter());
   await app.listen(3000);
 }

backend/src/main.ts

@@ -0,0 +1,26 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { IsString, IsNumber, IsObject } from 'class-validator';
+class Coordinate {
+  @IsNumber()
+  x: number;
+  @IsNumber()
+  y: number;
+}
+export class CoordinateResponseDto {
+  @ApiProperty({
+    example: 'OO 생성에 성공했습니다.',
+    description: 'api 요청 결과 메시지',
+  })
+  @IsString()
+  message: string;
+
+  @ApiProperty({
+    example: {
+      x: 14,
+      y: 14,
+    },
+    description: 'api 요청 결과 메시지',
+  })
+  @IsObject()
+  coordinate: Coordinate;
+}

backend/src/node/dtos/coordinateResponse.dto.ts

@@ -1,12 +1,25 @@
+import { ApiProperty } from '@nestjs/swagger';
 import { IsString, IsNumber } from 'class-validator';
 
 export class CreateNodeDto {
+  @ApiProperty({
+    example: '노드 제목',
+    description: '노드 제목',
+  })
   @IsString()
   title: string;
 
+  @ApiProperty({
+    example: '14',
+    description: 'x 좌표입니다.',
+  })
   @IsNumber()
   x: number;
 
+  @ApiProperty({
+    example: '14',
+    description: 'y 좌표입니다.',
+  })
   @IsNumber()
   y: number;
 }

backend/src/node/dtos/createNode.dto.ts

@@ -0,0 +1,11 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { IsString } from 'class-validator';
+
+export class MessageResponseDto {
+  @ApiProperty({
+    example: 'OO 생성에 성공했습니다.',
+    description: 'api 요청 결과 메시지',
+  })
+  @IsString()
+  message: string;
+}

backend/src/node/dtos/messageResponse.dto.ts

@@ -1,12 +1,25 @@
 import { IsString, IsNumber } from 'class-validator';
+import { ApiProperty } from '@nestjs/swagger';
 
 export class UpdateNodeDto {
+  @ApiProperty({
+    example: '노드 제목',
+    description: '노드 제목',
+  })
   @IsString()
   title: string;
 
+  @ApiProperty({
+    example: '14',
+    description: 'x 좌표입니다.',
+  })
   @IsNumber()
   x: number;
 
+  @ApiProperty({
+    example: '14',
+    description: 'y 좌표입니다.',
+  })
   @IsNumber()
   y: number;
 }

backend/src/node/dtos/updateNode.dto.ts

@@ -13,6 +13,9 @@ import {
 import { NodeService } from './node.service';
 import { CreateNodeDto } from './dtos/createNode.dto';
 import { UpdateNodeDto } from './dtos/updateNode.dto';
+import { ApiOperation, ApiResponse } from '@nestjs/swagger';
+import { MessageResponseDto } from './dtos/messageResponse.dto';
+import { CoordinateResponseDto } from './dtos/coordinateResponse.dto';
 
 export enum NodeResponseMessage {
   NODE_CREATED = '노드와 페이지를 생성했습니다.',
@@ -25,6 +28,10 @@ export enum NodeResponseMessage {
 export class NodeController {
   constructor(private readonly nodeService: NodeService) {}
 
+  @ApiResponse({
+    type: MessageResponseDto,
+  })
+  @ApiOperation({ summary: '노드를 생성하면서 페이지도 함께 생성합니다.' })
   @Post('/')
   @HttpCode(HttpStatus.CREATED)
   async createNode(@Body() body: CreateNodeDto): Promise<{ message: string }> {
@@ -33,7 +40,12 @@ export class NodeController {
       message: NodeResponseMessage.NODE_CREATED,
     };
   }
-
+  @ApiResponse({
+    type: MessageResponseDto,
+  })
+  @ApiOperation({
+    summary: '노드를 삭제하면서 페이지도 삭제합니다. (delete: cascade)',
+  })
   @Delete('/:id')
   @HttpCode(HttpStatus.OK)
   async deleteNode(@Param('id') id: number): Promise<{ message: string }> {
@@ -42,7 +54,10 @@ export class NodeController {
       message: NodeResponseMessage.NODE_DELETED,
     };
   }
-
+  @ApiResponse({
+    type: MessageResponseDto,
+  })
+  @ApiOperation({ summary: '노드의 제목, 좌표를 수정합니다.' })
   @Patch('/:id')
   @HttpCode(HttpStatus.OK)
   async updateNode(
@@ -54,7 +69,10 @@ export class NodeController {
       message: NodeResponseMessage.NODE_UPDATED,
     };
   }
-
+  @ApiResponse({
+    type: CoordinateResponseDto,
+  })
+  @ApiOperation({ summary: '노드의 좌표를 가져옵니다.' })
   @Get(':id/coordinates')
   @HttpCode(HttpStatus.OK)
   async getCoordinates(@Param('id', ParseIntPipe) id: number) {

backend/src/node/node.controller.ts

@@ -1,15 +1,32 @@
+import { ApiProperty } from '@nestjs/swagger';
 import { IsString, IsNumber, IsJSON } from 'class-validator';
 
 export class CreatePageDto {
+  @ApiProperty({
+    example: 'nest.js 사용법',
+    description: '페이지 제목입니다.',
+  })
   @IsString()
   title: string;
 
+  @ApiProperty({
+    example: 'nest를 설치합니다.',
+    description: '페이지 내용입니다.',
+  })
   @IsJSON()
   content: JSON;
 
+  @ApiProperty({
+    example: '14',
+    description: 'x 좌표입니다.',
+  })
   @IsNumber()
   x: number;
 
+  @ApiProperty({
+    example: '14',
+    description: 'y 좌표입니다.',
+  })
   @IsNumber()
   y: number;
 }

backend/src/page/dtos/createPage.dto.ts

@@ -0,0 +1,22 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { IsString, IsArray, IsObject } from 'class-validator';
+import { Page } from '../page.entity';
+
+export class FindPageResponseDto {
+  @ApiProperty({
+    example: 'OO 생성에 성공했습니다.',
+    description: 'api 요청 결과 메시지',
+  })
+  @IsString()
+  message: string;
+
+  @ApiProperty({
+    example: {
+      type: 'doc',
+      content: {},
+    },
+    description: '모든 Page 배열',
+  })
+  @IsObject()
+  page: Partial<Page>;
+}