NestJS에서 Zod와 Swagger 함께 사용하기 (Zod v4)

import * as z from "zod";
const schema = z.object({
  name: z.string().min(1, { message: "Name is required" }),
  age: z.number().min(0, { message: "Age must be non-negative" }),
  email: z.string().email({ message: "Invalid email address" }),
});

import { z } from "zod";
const schema = z.object({
  name: z.string().min(1, { errors: "Name is required" }),
  age: z.number().min(0, { errors: "Age must be non-negative" }),
  email: z.email({ errors: "Invalid email address" }),
});

npm install -g @nestjs/cli

nest new my-nestjs-project

npm install nestjs-zod zod @nestjs/swagger

nest generate module user --no-spec

nest generate controller user --no-spec

nest generate service user --no-spec

import { Controller, Get } from "@nestjs/common";
 
@Controller("users")
export class UserController {
  @Get()
  getUser() {
    return { message: "User endpoint" };
  }
}

import { NestFactory } from "@nestjs/core";
import { AppModule } from "./app.module";
import { DocumentBuilder, SwaggerModule } from "@nestjs/swagger";
import { cleanupOpenApiDoc } from "nestjs-zod";
 
async function bootstrap() {
  const app = await NestFactory.create(AppModule);
 
  const config = new DocumentBuilder()
    // setTitle - API 문서의 제목을 설정합니다.
    .setTitle("API Documentation")
    // setDescription - API 문서의 설명을 설정합니다.
    .setDescription("API description")
    // setVersion - API 문서의 버전을 설정합니다.
    .setVersion("1.0")
    // addServer - API 서버의 기본 URL을 추가합니다.
    .addServer("http://localhost:3000")
    // addTag - API 문서를 그룹화하는 태그를 추가합니다.
    .addTag("users")
    .build();
 
  const document = SwaggerModule.createDocument(app, config);
  SwaggerModule.setup("api-docs", app, cleanupOpenApiDoc(document));
 
  await app.listen(process.env.PORT ?? 3000);
}
bootstrap();

import { z } from "zod";
import { createZodDto } from "nestjs-zod";
import { ApiProperty } from "@nestjs/swagger";
 
export const createUserSchema = z.object({
  userName: z.string().min(1, { error: "사용자 이름은 필수입니다." }),
  email: z.email({ error: "유효한 이메일 주소여야 합니다." }),
  password: z
    .string()
    .min(6, { error: "비밀번호는 최소 6자 이상이어야 합니다." })
    .regex(/[A-Z]/, {
      error: "비밀번호에는 최소 하나의 대문자가 포함되어야 합니다.",
    }),
});
 
export class CreateUserDto extends createZodDto(createUserSchema) {
  @ApiProperty({
    description: "사용자 이름",
    example: "John",
    minLength: 1,
    type: String,
  })
  userName: string;
 
  @ApiProperty({
    description: "이메일 주소",
    example: "user@example.com",
    type: String,
    format: "email",
  })
  email: string;
 
  @ApiProperty({
    description: "비밀번호",
    example: "Password123",
    minLength: 6,
    type: String,
  })
  password: string;
}

import { Body, Controller, Get, Post } from "@nestjs/common";
import { CreateUserDto } from "./dto/user.dto";
import { UserService } from "./user.service";
import { ApiTags } from "@nestjs/swagger";
@ApiTags("users")
@Controller("users")
export class UserController {
  constructor(private readonly userService: UserService) {}
  @Get()
  getUser() {
    return { message: "User endpoint" };
  }
 
  @Post()
  createUser(@Body() createUserDto: CreateUserDto) {
    const { userName, email, password } = createUserDto;
    return `User created: ${userName}, ${email}, ${password}`;
  }
}

// ... 생략 ...
import { ZodValidationPipe } from "nestjs-zod";
 
// ... 생략 ...
  @Post()
  @UsePipes(ZodValidationPipe)
  createUser(@Body() createUserDto: CreateUserDto) {
    const { userName, email, password } = createUserDto;
    return `User created: ${userName}, ${email}, ${password}`;
  }

{
  "userName": "",
  "email": "invalid-email",
  "password": "short"
}

{
  "statusCode": 400,
  "message": "Validation failed",
  "errors": [
    {
      "origin": "string",
      "code": "too_small",
      "minimum": 1,
      "inclusive": true,
      "path": ["userName"],
      "message": "사용자 이름은 필수입니다."
    },
    {
      "origin": "string",
      "code": "invalid_format",
      "format": "email",
      "pattern": "/^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$/",
      "path": ["email"],
      "message": "유효한 이메일 주소여야 합니다."
    },
    {
      "origin": "string",
      "code": "too_small",
      "minimum": 6,
      "inclusive": true,
      "path": ["password"],
      "message": "비밀번호는 최소 6자 이상이어야 합니다."
    },
    {
      "origin": "string",
      "code": "invalid_format",
      "format": "regex",
      "pattern": "/[A-Z]/",
      "path": ["password"],
      "message": "비밀번호에는 최소 하나의 대문자가 포함되어야 합니다."
    }
  ]
}

import {
  ExceptionFilter,
  Catch,
  ArgumentsHost,
  HttpStatus,
} from "@nestjs/common";
import { Response } from "express";
import { ZodValidationException } from "nestjs-zod";
 
@Catch(ZodValidationException)
export class FirstMessageZodExceptionFilter implements ExceptionFilter {
  catch(exception: ZodValidationException, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse<Response>();
 
    const zodError = exception.getZodError() as any;
    const firstMessage = zodError.issues[0]?.message || "Validation failed";
 
    response.status(HttpStatus.BAD_REQUEST).json({
      statusCode: HttpStatus.BAD_REQUEST,
      message: firstMessage, // 첫 번째 메시지만 반환
    });
  }
}

// ... 생략 ...
import { FirstMessageZodExceptionFilter } from "./common/filters/zod-exceptions.filter";
// ... 생략 ...
async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  // 글로벌 예외 필터 등록
  app.useGlobalFilters(new FirstMessageZodExceptionFilter());
}

{
  "userName": "",
  "email": "invalid-email",
  "password": "short"
}

{
  "statusCode": 400,
  "message": "사용자 이름은 필수입니다."
}

import { Module } from "@nestjs/common";
import { APP_PIPE } from "@nestjs/core";
import { ZodValidationPipe } from "nestjs-zod";
import { UserModule } from "./user/user.module";
@Module({
  imports: [UserModule],
  providers: [
    {
      provide: APP_PIPE,
      useClass: ZodValidationPipe,
    },
  ],
})
export class AppModule {}

{
  "userName": "",
  "email": "invalid-email",
  "password": "short"
}

{
  "statusCode": 400,
  "message": "사용자 이름은 필수입니다."
}