Merge pull request #354 from boostcampwm-2024/docs/user-signup

📝 docs: 사용자 API swagger 작성

Author: asn6878

server/src/common/swagger/swagger.ts

@@ -14,6 +14,7 @@ export function setupSwagger(app: INestApplication) {
     .addTag('Feed', '피드 관리와 검색 관련 API')
     .addTag('RSS', '관리자 전용 API')
     .addTag('Statistic', '통계 정보 조회 API')
+    .addTag('User', '사용자 관리와 인증 관련 API')
     .setLicense('MIT License', 'https://opensource.org/licenses/MIT')
     .build();
 

server/src/user/api-docs/certificateUser.api-docs.ts

@@ -0,0 +1,40 @@
+import { applyDecorators } from '@nestjs/common';
+import {
+  ApiBadRequestResponse,
+  ApiNotFoundResponse,
+  ApiOkResponse,
+  ApiOperation,
+} from '@nestjs/swagger';
+
+export function ApiCertificateUser() {
+  return applyDecorators(
+    ApiOperation({
+      summary: '회원 인증 API',
+    }),
+    ApiOkResponse({
+      description: 'Ok',
+      schema: {
+        properties: {
+          message: {
+            type: 'string',
+          },
+        },
+      },
+      example: {
+        message: '회원 인증 요청이 성공적으로 처리되었습니다.',
+      },
+    }),
+    ApiBadRequestResponse({
+      description: 'Bad Request',
+      example: {
+        message: '오류 메세지',
+      },
+    }),
+    ApiNotFoundResponse({
+      description: 'Not Found',
+      example: {
+        message: '인증에 실패했습니다.',
+      },
+    }),
+  );
+}

server/src/user/api-docs/checkEmailDuplication.api-docs.ts

@@ -0,0 +1,40 @@
+import { applyDecorators } from '@nestjs/common';
+import {
+  ApiBadRequestResponse,
+  ApiOkResponse,
+  ApiOperation,
+  ApiUnauthorizedResponse,
+} from '@nestjs/swagger';
+
+export function ApiCheckEmailDuplication() {
+  return applyDecorators(
+    ApiOperation({
+      summary: '이메일 중복 조회 API',
+    }),
+    ApiOkResponse({
+      description: 'Ok',
+      schema: {
+        properties: {
+          message: {
+            type: 'string',
+          },
+        },
+      },
+      example: {
+        message: '이메일 중복 조회 요청이 성공적으로 처리되었습니다.',
+      },
+    }),
+    ApiBadRequestResponse({
+      description: 'Bad Request',
+      example: {
+        message: '오류 메세지',
+      },
+    }),
+    ApiUnauthorizedResponse({
+      description: 'Unauthorized',
+      example: {
+        message: '인증되지 않은 사용자입니다.',
+      },
+    }),
+  );
+}

server/src/user/api-docs/signupUser.api-docs.ts

@@ -0,0 +1,40 @@
+import { applyDecorators } from '@nestjs/common';
+import {
+  ApiBadRequestResponse,
+  ApiConflictResponse,
+  ApiOkResponse,
+  ApiOperation,
+} from '@nestjs/swagger';
+
+export function ApiSignupUser() {
+  return applyDecorators(
+    ApiOperation({
+      summary: '회원 가입 API',
+    }),
+    ApiOkResponse({
+      description: 'Ok',
+      schema: {
+        properties: {
+          message: {
+            type: 'string',
+          },
+        },
+      },
+      example: {
+        message: '회원가입이 요청이 성공적으로 처리되었습니다.',
+      },
+    }),
+    ApiBadRequestResponse({
+      description: 'Bad Request',
+      example: {
+        message: '오류 메세지',
+      },
+    }),
+    ApiConflictResponse({
+      description: 'Conflict',
+      example: {
+        message: '이미 존재하는 이메일입니다.',
+      },
+    }),
+  );
+}

server/src/user/controller/user.controller.ts

@@ -11,23 +11,35 @@ import {
 import { ApiResponse } from '../../common/response/common.response';
 import { UserService } from '../service/user.service';
 import { SignupDto } from '../dto/request/signup.dto';
+import { ApiCheckEmailDuplication } from '../api-docs/checkEmailDuplication.api-docs';
+import { ApiSignupUser } from '../api-docs/signupUser.api-docs';
+import { ApiCertificateUser } from '../api-docs/certificateUser.api-docs';
+import { CertificateDto } from '../dto/request/certificate.dto';
+import { CheckEmailDuplicationRequestDto } from '../dto/request/CheckEmailDuplcation.dto';
 
 @ApiTags('User')
 @Controller('user')
 export class UserController {
   constructor(private readonly userService: UserService) {}
 
+  @ApiCheckEmailDuplication()
   @Get('/email-check')
   @HttpCode(HttpStatus.OK)
-  async checkEmailDuplication(@Query('email') email: string) {
+  async checkEmailDuplication(
+    @Query()
+    checkEmailDuplicationRequestDto: CheckEmailDuplicationRequestDto,
+  ) {
     return ApiResponse.responseWithData(
       '이메일 중복 조회 요청이 성공적으로 처리되었습니다.',
       {
-        exists: await this.userService.checkEmailDuplication(email),
+        exists: await this.userService.checkEmailDuplication(
+          checkEmailDuplicationRequestDto.email,
+        ),
       },
     );
   }
 
+  @ApiSignupUser()
   @Post('/signup')
   @HttpCode(HttpStatus.CREATED)
   async signupUser(@Body() signupDto: SignupDto) {
@@ -37,10 +49,11 @@ export class UserController {
     );
   }
 
+  @ApiCertificateUser()
   @Post('/certificate')
   @HttpCode(HttpStatus.OK)
-  async certificateUser(@Body() uuid: string) {
-    await this.userService.certificateUser(uuid);
+  async certificateUser(@Body() certificateDto: CertificateDto) {
+    await this.userService.certificateUser(certificateDto.uuid);
     return ApiResponse.responseWithNoContent(
       '이메일 인증이 성공적으로 처리되었습니다.',
     );

server/src/user/dto/request/CheckEmailDuplcation.dto.ts

@@ -0,0 +1,14 @@
+import { IsEmail, IsNotEmpty } from 'class-validator';
+import { ApiProperty } from '@nestjs/swagger';
+import { Type } from 'class-transformer';
+
+export class CheckEmailDuplicationRequestDto {
+  @ApiProperty({
+    example: 'test1234@test.com',
+    description: '중복 확인할 이메일을 입력해주세요.',
+  })
+  @IsEmail({}, { message: '이메일 형식이 아닙니다.' })
+  @IsNotEmpty({ message: '이메일을 입력해주세요.' })
+  @Type(() => String)
+  email: string;
+}

server/src/user/dto/request/certificate.dto.ts

@@ -0,0 +1,13 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { IsNotEmpty } from 'class-validator';
+
+export class CertificateDto {
+  @ApiProperty({
+    example: 'd2ba0d98-95ce-4905-87fc-384965ffe7c9',
+    description: '인증 코드를 입력해주세요.',
+  })
+  @IsNotEmpty({
+    message: '인증 코드를 입력해주세요.',
+  })
+  uuid: string;
+}

server/src/user/dto/request/signup.dto.ts

@@ -1,7 +1,12 @@
 import { IsEmail, IsNotEmpty } from 'class-validator';
 import { User } from '../../entity/user.entity';
+import { ApiProperty } from '@nestjs/swagger';
 
 export class SignupDto {
+  @ApiProperty({
+    example: 'test123@test.com',
+    description: '이메일을 입력해주세요.',
+  })
   @IsEmail(
     {},
     {
@@ -13,11 +18,19 @@ export class SignupDto {
   })
   email: string;
 
+  @ApiProperty({
+    example: 'test1234!',
+    description: '비밀번호를 입력해주세요.',
+  })
   @IsNotEmpty({
     message: '비밀번호가 없습니다.',
   })
   password: string;
 
+  @ApiProperty({
+    example: '홍길동',
+    description: '사용자 이름을 입력해주세요.',
+  })
   @IsNotEmpty({
     message: '사용자 이름이 없습니다.',
   })