[Nest.js] swagger 데코레이터 - 3 (보안)

1. @ApiPearerAuth()

- 용도: JWT나 Bearer 토큰 인증을 사용하는 API를 문서화

- 사용 시점: 컨트롤러 클래스 또는 메소드 레벨

// main.ts에서 글로벌 설정
const config = new DocumentBuilder()
  .setTitle('API 문서')
  .addBearerAuth()  // Bearer 인증 활성화
  .build();

// 컨트롤러에서 사용
@ApiBearerAuth()
@UseGuards(JwtAuthGuard)
@Controller('users')
export class UsersController {
  @Get('profile')
  @ApiBearerAuth('JWT-auth')  // 특정 보안 스키마 지정
  getProfile(@Request() req) {
    return req.user;
  }
}

 

2. ApiBasicAuth()

- 목적: Basic 인증(username/password)을 사용하는 API를 문서화

// main.ts 설정
const config = new DocumentBuilder()
  .addBasicAuth()
  .build();

// 컨트롤러에서 사용
@ApiBasicAuth()
@UseGuards(BasicAuthGuard)
@Controller('admin')
export class AdminController {
  @Get()
  getAdminDashboard() {}
}

 

3. @ApiCookieAuth()

- 용도: 쿠키 기반 인증을 사용하는 API를 문서화

// main.ts 설정
const config = new DocumentBuilder()
  .addCookieAuth('session-id')  // 쿠키 이름 지정
  .build();

@ApiCookieAuth()
@Controller('session')
export class SessionController {
  @Get('data')
  getSessionData() {}
}

 

4. @ApiSecurity()

- 용도: 커스텀 보안 스키마를 정의할 때 사용

// main.ts 설정
const config = new DocumentBuilder()
  .addSecurity('api_key', {
    type: 'apiKey',
    in: 'header',
    name: 'X-API-KEY'
  })
  .build();

@ApiSecurity('api_key')
@Controller('api')
export class ApiController {}