1. 준비물 및 개요

• "@nestjs/swagger": "^6.0.5"
• express-basic-auth

자세한 준비물은 공식문서 참고하면 된다.

• express를 사용할 때에는 swagger-autogen을 이용해서 API 명세서 작업을 했었다. 편리하긴 했지만, 수작업으로 하드코딩해야하는 사항들이 많아, 그렇게 꼼꼼하게 swagger 작업을 하지는 못했었다.
• nest에서는 @nest/swagger로 하여금, swagger 작업 시에 exrpess보다 좀 더 효율적으로 swagger 작업을 할 수 있다.

2. 기본 세팅

main.ts

  const config = new DocumentBuilder()
  .setTitle('Cats example')
  .setDescription('The cats API description').setVersion('1.0').addTag('cats').build(); // swagger 세팅
  const document = SwaggerModule.createDocument(app, config); // swagger 세팅
  SwaggerModule.setup('docs', app, document); // swagger 세팅

• main.ts에서 위와 같이 세팅해준다.

3. API 명세서 작성

• controller에서 다음과 같이 작업해줄 수 있다.

controller

  @ApiOperation({ summary: '회원가입' }) //swagger에서 api summary
  @ApiResponse({ status: 500, description: 'Server error' }) // swagger에서  response 케이스 표출
  @ApiResponse({ status: 200, description: 'success', type: ReadOnlyCatDto }) // swagger에서  response 케이스 표출
  @Post()
  // DTO(Data Transfer Object): 계층 간 데이터 교환을 위한 데이터 규격을 의미하는 객체
  // request를 받고, 각 계층 간 통신 시 데이터의  validation을 위해 이용된다.
  async signup(@Body() body: CatRequestDto) {
    // body는 @nestjs/swagger에서 인식하여 보여준다.
    return await this.catsService.signup(body);
  }
-------------------
schema
  @ApiProperty({
    // swagger에서 각 값에 대한 설명 추가
    example: 'example@naver.com',
    description: 'email',
    required: true,
  })
  @Prop({
    //스키마에 들어가는 각 데이터들의 옵션 설정
    required: true,
    unique: true,
  })
  @IsEmail()
  @IsNotEmpty()
  email: string;

• ApiOperation: api에 대한 요약
• ApiResponse: api의 response 케이스 설명
• ApiProperty: api에서 사용되는 각 값에 대한 설명(주로 스키마에서 작업하여, dto로 상속해서 사용)

4. swagger 접근에 계정 제한 설정

• swagger를 아무나 접근하게 한다면, 보안에 치명적인 약점이 생기게 되기 마련이다.
• 이에, 협업하는 FE에서만 swagger에 접근하도록 계정 제한을 설정할 필요가 있는데, 이 때 유용하게 활용할 수있는 라이브러리가 exrpess-basic-auth이다.
• app의 기본 설정에서 다음과 같이 swagger 경로에 접근 가능한 계정과 비밀번호를 설정할 수 있다.

main.ts

asnyc function bootstrap() {
  // swagger uri인 /docs에 계정 권한 설정
  app.use(
    ['/docs', '/docs-json'],
    basicAuth({
      challenge: true,
      users: {
        [process.env.swaggerUser]: process.env.swaggerPassword,
      },
    }),
  );
  const config = new DocumentBuilder().setTitle('Cats example').setDescription('The cats API description').setVersion('1.0').addTag('cats').build(); // swagger 세팅
  const document = SwaggerModule.createDocument(app, config); // swagger 세팅
  SwaggerModule.setup('docs', app, document); // swagger 세팅
}

참고자료

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