Nest.js Swagger 설치 및 설정

Swagger

Swagger는 서버와 상호작용이 가능한 API 들을 문서화 하여 제공하는데 사용되는 라이브러리 입니다. 해당 라이브러리를 사용하면 간단하게 서버에 요청을 보내 볼 수 있고 어떤 값을 필요로 하는지, 그리고 어떤 값이 반환이 되는지 문서를 통해 알 수 있습니다. 

 

Swagger 설치

npm install @nestjs/swagger swagger-ui-express

 

모듈 설정

import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger';

// ... 기존 코드 ...

async function bootstrap() {
  const app = await NestFactory.create(AppModule);

  // Swagger 옵션 설정
  const config = new DocumentBuilder()
    .setTitle('API 제목')
    .setDescription('API 설명')
    .setVersion('1.0')
    .build();
  
  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api-docs', app, document);

  await app.listen(3000);
}
bootstrap();

 

 

적용하기

Entity 에 Swagger Decorator 적용

// auth.dto 

export class SignupReqDto {
  @ApiProperty({ required: true, example: 'nestjs@fastcampus.com' })
  @IsEmail()
  @MaxLength(30)
  email: string;

  @ApiProperty({ required: true, example: 'Password1!' })
  @Matches(/^(?=.*\d)(?=.*[a-z])(?=.*[A-Z])(?=.*[!@#$%^&*]).{10,30}$/)
  password: string;

  @ApiProperty({ required: true, example: 'Password1!' })
  @Matches(/^(?=.*\d)(?=.*[a-z])(?=.*[A-Z])(?=.*[!@#$%^&*]).{10,30}$/)
  passwordConfirm: string;
}

// auth.controller

@ApiTags('Auth')
@ApiExtraModels(SignupResDto, SigninResDto)
@Controller('api/auth')
export class AuthController {
  constructor(private authService: AuthService) {}

  @ApiPostResponse(SignupResDto)
  @Post('signup')
  async signup(@Body() { email, password, passwordConfirm }: SignupReqDto) {
    if (password !== passwordConfirm) throw new BadRequestException();

    const { id } = await this.authService.signup(email, password);
    return { id };
  }

  @ApiPostResponse(SigninResDto)
  @Post('signin')
  async signin(@Body() { email, password }: SigninReqDto) {
    return this.authService.signin(email, password);
  }
}

 

Decorator	설명
@ApiProperty	해당 속성값에 대한 설명을 입력하는 데코레이터.
@ApiTags	Swagger 내에 카테고리를 구분하기 위해 적어 놓는 데코레이터.
@ApiExtraModels	Request 요청시에 Body에 담겨오지 않는 내용들은 Swagger에 문서화 되지 않는 문제가 있습니다. 해당 문제를 해결하기 위해 수동으로 입력 하는 데코레이터.
@ApiPostResponse	기본으로 제공되는 데코레이터가 아닙니다. 데코레이터에 대한 값을 커스텀을 하여 사용하고 있는 예시.