01. 데코레이터
- @ApiProperty()
- 클래스의 속성을 문서화할 때 사용. 속성에 대한 설명, 예제 값 및 다른 정보를 제공할 수 있다.
import { ApiProperty } from '@nestjs/swagger';
export class CreateCatDto {
@ApiProperty()
name: string;
@ApiProperty({
type: Number,
description: 'The age of a cat',
minimum: 1,
default: 1,
})
age: number;
@ApiProperty()
breed: string;
}
- @ApiOperation()
- 컨트롤러의 메서드를 문서화할 때 사용된다. 메서드의 요약, 설명 및 응답 타입을 지정할 수 있다.
import { ApiOperation } from '@nestjs/swagger';
@ApiOperation({ summary: 'Get a list of users' })
@Get()
getUsers(): Promise<User[]> {
// ...
}
- @ApiTags()
- 컨트롤러나 클래스에 태그를 추가하여 API 엔드포인트를 그룹화한다.
import { ApiTags } from '@nestjs/swagger';
@ApiTags('users')
@Controller('users')
export class UsersController {
// ...
}
- @ApiResponse()
- 컨트롤러 메서드의 응답을 문서화할 때 사용된다. 각 응답에 대한 설명 및 응답 상태 코드를 지정할 수 있다.
import { ApiResponse } from '@nestjs/swagger';
@ApiResponse({ status: 200, description: 'User found' })
@ApiResponse({ status: 404, description: 'User not found' })
@Get(':id')
getUser(@Param('id') id: string): Promise<User> {
// ...
}
- @ApiBearerAuth()
- Swagger UI에서 토큰 인증을 시뮬레이션하고 인증에 필요한 토큰을 입력할 수 있게 해준다.
import { Controller, Get, UseGuards } from '@nestjs/common';
import { ApiBearerAuth, ApiResponse, ApiTags } from '@nestjs/swagger';
import { JwtAuthGuard } from './jwt-auth.guard'; // 토큰 인증을 위한 커스텀 가드 예시
@ApiTags('products')
@ApiBearerAuth() // 이 데코레이터를 추가하여 토큰 인증을 Swagger에 지정합니다.
@Controller('products')
export class ProductsController {
constructor() {}
@Get()
@UseGuards(JwtAuthGuard) // 토큰 인증 가드를 사용하여 엔드포인트를 보호합니다.
@ApiResponse({ status: 200, description: 'Get all products' })
getAllProducts(): string[] {
return ['Product 1', 'Product 2', 'Product 3'];
}
}
