NestJs 프로젝트에서 Swagger 사용하기

https://swagger.io/

API Documentation & Design Tools for Teams | Swagger

프로젝트가 커질수록, 팀 프로젝트를 할수록 문서화하는것은 매우 중요하다. REST API 수가 많아질수록, 팀원들과 소통하기 위해 문서화 작업은 필수입니다.

 

문서화 작업을 위한 swagger 우리함께 배워봅시다. 😊

🤷 Swagger란?

API 설계와 문서화를 위한 오픈 소스 도구입니다. 이를 사용하면 개발자들이 API를 보다 쉽게 이해하고 사용할 수 있도록 문서를 작성하고, 테스트하고, 실행할 수 있습니다.

 

Swagger는 API 설계를 위한 강력한 도구로서, RESTful API를 작성하는 데 사용됩니다. Swagger를 사용하면 개발자는 API의 엔드포인트, 파라미터, 헤더, 응답 유형 등의 세부 정보를 문서화하고, 이를 바탕으로 API를 쉽게 테스트할 수 있습니다. 또한 Swagger를 사용하면 API 클라이언트를 자동으로 생성할 수 있어 개발 시간을 단축시킬 수 있습니다.

🔧 swagger 설치

[npm]
npm install --save @nestjs/swagger swagger-ui-express

[yarn]
yarn add @nestjs/swagger swagger-ui-express --dev

🔨 swaggerModule 설정하기

다음으로, SwaggerModule을 설정해야 합니다. SwaggerModule은 Swagger 문서를 생성하고 노출하기 위한 모듈입니다.

아래의 코드는 swagger을 사용하기위한 기본세팅입니다.

main.ts로 가서 코드를 작성해주세요. !! 

 

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

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

  const config = new DocumentBuilder()
    .setTitle('API 문서')
    .setDescription('API 문서입니다.')
    .setVersion('1.0')
    .build();

  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup('api', app, document);

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

 

위 코드에서 DocumentBuilder를 사용하여 Swagger 문서의 제목, 설명, 버전 등을 정의할 수 있습니다. 그리고 SwaggerModule.createDocument 메서드를 사용하여 DocumentBuilder에서 생성된 설정을 기반으로 Swagger 문서를 만듭니다. 마지막으로 SwaggerModule.setup을 호출하여 Swagger UI를 사용하여 노출할 API 문서의 경로를 지정합니다.

 

위와같이 main.ts에 세팅 하였다면 http://localhost:3000/api 경로로가면 Swagger UI를 확인할 수 있습니다.

 

🎨 swagger 사용하기

기초세팅 완료후 @nestjs/swagger에서 제공하는 어노테이션들을 하나씩 알아보고 사용해봅시다.🌝🌝

import { 필요한 데코레이터 } from @nestjs/swagger

[ Controller에서 주로 사용하는 어노테이션에 대해 알아보자! ]

import { ApiTags, ApiOperation, ApiBody, ApiResponse} from '@nestjs/swagger'

@ApiTags('사용자 API')
@Controller('user')
export class UserController {
  constructor(private readonly userService: UserService) {}

  @Post()
  @ApiOperation({ summary: '회원가입', description: '사용자 정보를 추가합니다.' })
  @ApiBody({ type: UserDTO.Request.SignUp })
  @ApiResponse({ status: 201, description: '회원가입에 성공하였습니다' })
  @ApiResponse({ status: 404, description: '회원가입에 실패하였습니다' })
   create(@Body() uerDTO: UserDTO.Request.SignUp) {
    return this.userService.create(uerDTO);
  }
}

 @ApiTags(),  @ApiOperation(), @ApiResponse(), @ApiBody() 4가지의 어노테이션을 사용하여 회원가입 api 문서를 작성해 보았습니다.

 

 

각 어노테이션에 대해 설명드리자면,

•  @ApiTags() : API 문서에 태그를 추가합니다.
•  @ApiOperation() : 메서드에 대한 설명을 추가합니다
•  @ApiResponse()  : API 메서드에서 연산의 응답에 대한 정보를 추가합니다.
•  @ApiBody() :  API 메서드에서 요청 바디의 정보를 추가합니다.

 

 

그외에도 @ApiParam(), @ApiQuery() 등이 존재합니다.

@Get(':id')
async findOne(@Param('id', ApiParam({ description: '회원 ID' })) id: string) {
  // ...
}

@Get()
async findAll(@Query('name', ApiQuery({ description: 'User name' })) name: string) {
  // ...
}

• @ApiParam() : API 메서드에서 요청 매개 변수의 정보를 추가합니다.
• @ApiQuery()  : API 메서드에서 쿼리 매개 변수의 정보를 추가합니다.

[  DTO(Data Transfer Object)에서 자주 사용하는 어노테이션에 대해 알아보자! ]

import { ApiProperty } from "@nestjs/swagger";
 
export namespace UserDTO {

    export namespace Request {

        export class SignIn {

            @ApiProperty({ description: '이메일', default: 'test@test.com' })
            email: string;

            @ApiProperty({ description: '비밀번호', default: 'test' })
            password: string;
        }

        export class SignUp {

            @ApiProperty({ description: '이메일', default: 'test@test.com' })
            email: string;
             
            @ApiProperty({ description: '비밀번호', default: 'test' })
            password: string;

            @ApiProperty({ description: '닉네임', default: 'hodu' })
            nickname: string;
        }
    }
}

@ApiProperty 어노테이션을 사용하여 해당 프로퍼티에 대한 추가 정보를 제공해보았습니다.

 

자 이렇게 완성된 api 문서를 확인해보면 잘 정리되어있는것을 확인하실수있습니다.

[ 인증에 관한 어노테이션에 대해 알아보자! ]

@ApiBearerAuth() 데코레이터는 Swagger 문서에서 인증 방식을 나타내기 위해 사용됩니다. 이 데코레이터는 Bearer Token 방식으로 인증하는 API의 문서에서 사용됩니다. 따라서 이 데코레이터는 Swagger UI에서 "Authorize" 버튼을 클릭하면 토큰 값을 입력할 수 있는 입력창을 보여주도록 설정합니다. 

 

예시는 회원탈퇴시 토큰값이 유효한지 확인하도록 합니다.

  @Delete('/')
    @ApiBearerAuth()
    @ApiOperation({ summary: '회원탈퇴', description: '사용자 정보를 삭제합니다.' })
    @UseGuards(AuthGuard)
    async withdrawal(
        @User() user: UserEntity
    ) {
        const results = await this.userService.delete(user);
        return plainToInstance(UserDTO.Response.Profile, results);
    }

https://develop-const.tistory.com/12

만약  JWT 토큰이 유효한지 확인해주는 guard에 대한 예시를 보고싶다면 아래를 클릭해주세요!

NestJs Guard에 대해 알아보자

 

좀 더많은 swagger 어노테이션에 대한 정보를 확인하고싶다면 아래를 클릭해주세요!

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