24/01/02 TIL __ nest에서 swagger 사용하기

 

 

 

swagger를 사용하면 api문서 자동화가 되어 편리하다고 들었다. 

이전부터 사용해 보고 싶었지만 프로젝트랑 이것저거서 하며 미뤄오다가 

캠프 동기분께서 감사하게도 알려주셔서 정리하게 되었다. 

 

 

사용법은 nest js공식문서에 잘 나와있어서 아래 링크를 첨부한다. 

 

https://docs.nestjs.com/openapi/introduction

Documentation | NestJS - A progressive Node.js framework

https://docs.nestjs.com/openapi/types-and-parameters

Documentation | NestJS - A progressive Node.js framework

 

https://docs.nestjs.com/openapi/cli-plugin

 

 

 

링크를 걸어둔 순서대로 잘 따라가면 사용할 수 있는데, 

새롭게 알게된 몇가지 사실을 정리해 보려고 한다. 

 

 

 

1. @ApiProperty({example: "eh@naver.com"}) 이 아니여도 된다. 

그럼 어떻게 하냐면

 

user.entity.ts.

  /**
   * 이메일
   * @example "email@example.com"
   */
  @IsNotEmpty({ message: '이메일 입력바람' })
  @IsEmail({}, { message: '이메일 형식이 아닌데요' })
  @Column({ unique: true })
  email: string;

 

이런식으로 설정해 줘도 똑같이 작동한다. 

데코레이터가 많아서 헷갈리는 경우 유용하게 사용할 듯 하다. 

 

 

 

2. 기본 설정

main.ts

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { ConfigService } from '@nestjs/config';
import { ValidationPipe } from '@nestjs/common';
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  const configService = app.get(ConfigService); //컨피그 써비스 찾아서 변수에 담기.
  const port = configService.get<number>('PORT');

  app.setGlobalPrefix('api');
  app.useGlobalPipes(
    new ValidationPipe({
      transform: true, //해당 타입으로 자동 변경되도록.
      whitelist: true, //dto에 정의되지 않은 값은 에러
      forbidNonWhitelisted: true,
    }),
  );

  const config = new DocumentBuilder()
    .setTitle('nest 개인과제 해설영상')
    .setDescription('네스트 개인과제 해설영상을 보며 테스트 ')
    .setVersion('1.0')
    .addTag('api')
    .build();
  const document = SwaggerModule.createDocument(app, config);

  //이거 빼먹으면 스웨거 이그젬플 벨류 값안됨.
  SwaggerModule.setup('api', app, document, {
    swaggerOptions: {
      persistAuthorization: true, //사용자가 입력한 인증정보를 지속적으로 저장할지.(내가 트루로 설정하면 새로고침해도 인증정보 유지. 경로이동 해도 유지)
      tagSorter: 'alpha', // 태그정렬은 알파벳 순으로 하겠다.
      operationSorter: 'alpha', //엔드포인트 정렬은 알파벳 순으로 하겠다.
    },
  });
  await app.listen(port);
}
bootstrap();

 

이부분에서 swaggerModule.setup 부분을 빼먹어서  예상과 다르게 작동이 되었었다. 

여러 스웨거 옵션을 설정해 주는 작업이고 필요에 따라서 사용하면 될꺼 같다. 

 

 

 

 persistAuthorization: true 이 옵션은 true로 하는게 좋을듯 한데,

이유는 인증 정보가 계속 사라지기 때문에 토큰을 유지시키려면 걸어두는게 좋았다. 

 

 

 

3. swagger용 예시를  entitiy에 적어두고, dto에는 다음과 같이 해도 된다. 

export class SignUpDto extends PickType(User, [
  'email',
  'password',
  'nickname',
]) {
  //dto만 넣으면 되는게 아니라 entity에도 넣어야 정상작동함.
  /**
   * 비번 확인
   * @example '비번 확인'
   */
  @IsNotEmpty({ message: '비밀번호 확인 해주세요.' })
  @IsStrongPassword(
    {},
    {
      message:
        '비밀번호는 영문 알파벳 대, 소문자, 숫자, 특수문자를 포함해야 합니다.',
    },
  ) 
  passwordConfirm: string;
}

 

원리는 User라는 엔티티에 내용들 중에서 email, password, nickname을 가져올수 있으니 그렇게 작동 하는것.

그리고 추가로 User엔티티에 없는 내용을 추가하려면 아래에 추가해주면 되고, swagger예시도 적어주면 된다. 

 

 

처음에는 api명세를 코드로 한다는게 어색했는데,

사용하기 크게 어렵지 않아서 길게보면 오히려 편할것 같았다. 

그리고 무었보다 vscode내부에서 작동하는게 아니라

웹사이트를 켜서 작동하다 보니 좀더 편리한 느낌도 있다. (왔다갔다 안해도 되는 ㅋㅋㅋㅋ)