swagger와 본캠프 TIL 01/27

Swagger는 API 설계와 문서화를 위한 오픈 소스 도구로, 개발자들이 API를 쉽게 이해하고 활용할 수 있도록 돕는 강력한 도구입니다. -- 웹으로 실행하는 인섬니아같은 도구라고 생각하면 됩니다!!

 

이를 통해 API 엔드포인트, 파라미터, 헤더, 응답 유형 등의 정보를 문서화하고 테스트할 수 있습니다. Swagger는 자동으로 API 클라이언트를 생성할 수 있어 개발 효율성을 높이는 데 기여합니다.

 

Swagger 설치 방법

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

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();

위 설정 후 브라우저에서 http://localhost:3000/api로 접속하면 Swagger UI를 확인할 수 있습니다.

 

Swagger 데코레이터 활용

@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() userDTO: UserDTO.Request.SignUp) {
    return this.userService.create(userDTO);
  }
}

 

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

 

추가적으로 @ApiParam()과 @ApiQuery()를 사용해 요청 매개변수와 쿼리 매개변수 정보를 문서화할 수 있습니다.

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

@Get()
@ApiQuery({ name: 'name', description: '사용자 이름' })
async findAll(@Query('name') name: string) {
  // ...
}

 

 

DTO에 Swagger 데코레이터 적용

DTO에 @ApiProperty를 사용하면 요청/응답 데이터에 대한 정보를 문서화할 수 있습니다.

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;
    }
  }
}

이렇게 설정한 Swagger 문서는 API 사용법을 체계적으로 정리하여 개발자들이 쉽게 이해하고 활용할 수 있도록 돕습니다!