Swagger를 이용한 API 문서화

npm install @nestjs/swagger

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';
import { ValidationPipe } from '@nestjs/common';
import { SwaggerModule, DocumentBuilder } from '@nestjs/swagger'; // Swagger 관련 모듈 임포트

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

  // 전역 유효성 검사 파이프 설정 (이전 절에서 다룸)
  app.useGlobalPipes(new ValidationPipe({
    whitelist: true,
    forbidNonWhitelisted: true,
    transform: true,
    disableErrorMessages: process.env.NODE_ENV === 'production',
  }));

  // Swagger 설정 시작
  const config = new DocumentBuilder()
    .setTitle('Users API Example') // API 문서의 제목
    .setDescription('The Users API description with CRUD operations.') // API 문서 설명
    .setVersion('1.0') // API 버전
    .addTag('users', 'User related endpoints') // API에 태그 추가 (컨트롤러 그룹화에 사용)
    .addBearerAuth( // OpenAPI Bearer 보안 스키마 정의
      { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' },
      'access-token' // @ApiBearerAuth()에서 참조할 보안 스키마 이름
    )
    .build();

  // 문서가 요청될 때 직렬화 가능한 OpenAPI 문서 객체 생성
  const documentFactory = () => SwaggerModule.createDocument(app, config);

  // /api 경로에 Swagger UI를 서빙하도록 설정
  // 이 경로로 접속하면 API 문서를 웹에서 볼 수 있습니다.
  SwaggerModule.setup('api', app, documentFactory);
  // Swagger 설정 끝

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

import { IsString, IsEmail, IsNotEmpty, IsInt, Min, Max } from 'class-validator';
import { ApiProperty } from '@nestjs/swagger'; // ApiProperty 임포트

export class CreateUserDto {
  @ApiProperty({ description: '사용자 이름', example: '홍길동' }) // Swagger UI에 표시될 속성 정보
  @IsString({ message: '이름은 문자열이어야 합니다.' })
  @IsNotEmpty({ message: '이름은 필수 항목입니다.' })
  name: string;

  @ApiProperty({ description: '사용자 이메일 (고유)', example: 'hong.gd@example.com' })
  @IsEmail({}, { message: '유효한 이메일 형식이 아닙니다.' })
  @IsNotEmpty({ message: '이메일은 필수 항목입니다.' })
  email: string;

  @ApiProperty({ description: '사용자 나이', example: 30, minimum: 0, maximum: 150 })
  @IsInt({ message: '나이는 정수여야 합니다.' })
  @Min(0, { message: '나이는 0 이상이어야 합니다.' })
  @Max(150, { message: '나이는 150보다 작거나 같아야 합니다.' })
  age: number;
}

import { PartialType } from '@nestjs/swagger';
import { CreateUserDto } from './create-user.dto';

// PartialType은 CreateUserDto의 모든 필드를 선택적(optional)으로 만들고,
// 해당 필드에 대한 @ApiProperty() 정의도 자동으로 상속합니다.
export class UpdateUserDto extends PartialType(CreateUserDto) {}

import { Controller, Get, Post, Body, Param, Patch, Delete, HttpCode, HttpStatus, NotFoundException } from '@nestjs/common';
import { UsersService, User } from './users.service'; // 런타임 응답 모델 class 임포트
import { CreateUserDto } from './dto/create-user.dto';
import { UpdateUserDto } from './dto/update-user.dto';
import {
  ApiTags, // 컨트롤러에 태그를 지정
  ApiOperation, // API 작업에 대한 설명
  ApiResponse, // 특정 HTTP 상태 코드에 대한 응답 설명
  ApiParam, // 경로 파라미터 설명
  ApiBody, // 요청 본문 설명
} from '@nestjs/swagger';

@ApiTags('users') // 이 컨트롤러의 모든 API를 'users' 태그로 그룹화합니다.
@Controller('users')
export class UsersController {
  constructor(private readonly usersService: UsersService) {}

  @Get()
  @ApiOperation({ summary: '모든 사용자 조회', description: '등록된 모든 사용자 목록을 반환합니다.' })
  @ApiResponse({ status: 200, description: '성공적으로 모든 사용자를 반환합니다.', type: [User] }) // User[] 타입을 명시하여 응답 스키마 표시
  findAll(): User[] { // 반환 타입 명시
    return this.usersService.findAll();
  }

  @Get(':id')
  @ApiOperation({ summary: '특정 사용자 조회', description: 'ID를 사용하여 특정 사용자를 조회합니다.' })
  @ApiParam({ name: 'id', description: '조회할 사용자의 고유 ID', example: 1 })
  @ApiResponse({ status: 200, description: '성공적으로 사용자를 반환합니다.', type: User })
  @ApiResponse({ status: 404, description: '사용자를 찾을 수 없습니다.' })
  findOne(@Param('id') id: string): User {
    const user = this.usersService.findOne(+id);
    if (!user) {
      throw new NotFoundException(`User with ID ${id} not found`);
    }
    return user;
  }

  @Post()
  @ApiOperation({ summary: '새 사용자 생성', description: '새로운 사용자 계정을 생성합니다.' })
  @ApiBody({ type: CreateUserDto, description: '생성할 사용자 정보' }) // 요청 본문의 타입을 명시
  @ApiResponse({ status: 201, description: '성공적으로 사용자 생성.', type: User })
  @ApiResponse({ status: 400, description: '유효하지 않은 요청 본문입니다.' })
  @HttpCode(HttpStatus.CREATED)
  create(@Body() createUserDto: CreateUserDto): User {
    return this.usersService.create(createUserDto);
  }

  @Patch(':id')
  @ApiOperation({ summary: '사용자 정보 부분 수정', description: 'ID를 사용하여 특정 사용자의 정보를 부분적으로 수정합니다.' })
  @ApiParam({ name: 'id', description: '수정할 사용자의 고유 ID' })
  @ApiBody({ type: UpdateUserDto, description: '수정할 사용자 정보 (일부만 포함 가능)' })
  @ApiResponse({ status: 200, description: '성공적으로 사용자 정보 수정.', type: User })
  @ApiResponse({ status: 404, description: '사용자를 찾을 수 없습니다.' })
  @ApiResponse({ status: 400, description: '유효하지 않은 요청 본문입니다.' })
  update(@Param('id') id: string, @Body() updateUserDto: UpdateUserDto): User {
    const updatedUser = this.usersService.update(+id, updateUserDto);
    if (!updatedUser) {
      throw new NotFoundException(`User with ID ${id} not found`);
    }
    return updatedUser;
  }

  @Delete(':id')
  @ApiOperation({ summary: '사용자 삭제', description: 'ID를 사용하여 특정 사용자를 삭제합니다.' })
  @ApiParam({ name: 'id', description: '삭제할 사용자의 고유 ID' })
  @ApiResponse({ status: 204, description: '성공적으로 사용자 삭제 (응답 본문 없음).' })
  @ApiResponse({ status: 404, description: '사용자를 찾을 수 없습니다.' })
  @HttpCode(HttpStatus.NO_CONTENT)
  remove(@Param('id') id: string): void { // void로 반환 타입을 명시
    const removed = this.usersService.remove(+id);
    if (!removed) {
      throw new NotFoundException(`User with ID ${id} not found`);
    }
  }
}

import { Injectable } from '@nestjs/common';
import { ApiProperty } from '@nestjs/swagger';

export class User {
  @ApiProperty({ example: 1 })
  id!: number;

  @ApiProperty({ example: '홍길동' })
  name!: string;

  @ApiProperty({ example: 'hong.gd@example.com' })
  email!: string;

  @ApiProperty({ example: 30 })
  age!: number;
}

@Injectable()
export class UsersService {
  // ... 기존 코드
}