[Nest.js] swagger 데코레이터 - 1

1. @ApiOperation()

- 용도: API 엔드포인트의 동작을 설명하는 메타 데이터 정의

- 사용 시점: 컨트롤러의 각 메소드에 정의

@ApiOperation({
  summary: '게시글 목록 조회',      // API 요약 설명
  description: '페이지네이션을 포함한 게시글 목록을 조회합니다', // 상세 설명
  deprecated: false               // API 폐기 여부
})

 

2. @ApiTags()

- 용도: API들을 논리적인 그룹으로 분류

- 사용 시점: 컨트롤러 클래스 레벨에 정의

// 컨트롤러 레벨에서 사용
@ApiTags('posts')            // 단일 태그
@ApiTags('posts', 'admin')   // 복수 태그
@Controller('posts')
export class PostsController {}

 

3. @ApiHeader()

- 용도: API 요청에 필요한 HTTP 헤더를 문서화

- 사용 시점: 컨트롤러 메소드나 클래스 레벨에 정의

@ApiHeader({
  name: 'Authorization',         // 헤더 이름
  description: 'Auth token',     // 헤더 설명
  required: true,               // 필수 여부
  example: 'Bearer {token}'     // 예시 값
})

 

4. @ApiQuery()

- 용도: URL 쿼리 파라미터를 문서화

- 사용 시점: 쿼리 파라미터를 받는 메소드에 적용

@ApiQuery({
  name: 'page',                // 쿼리 파라미터 이름
  required: false,             // 필수 여부
  type: Number,               // 타입
  description: '페이지 번호',    // 설명
  example: 1,                 // 예시 값
  enum: ['ASC', 'DESC']       // enum 타입인 경우
})
@ApiQuery({
  name: 'filter',
  schema: {                   // 복잡한 타입 정의
    type: 'object',
    properties: {
      status: { type: 'string' },
      type: { type: 'integer' }
    }
  }
})

 

5. @ApiParam()

- 용도: URL 경로 파라미터를 문서화

- 사용 시점: 경로 파라미터를 사용하는 메소드에 적용

@ApiParam({
  name: 'id',                 // URL 파라미터 이름
  type: 'number',            // 타입
  description: '게시글 ID',    // 설명
  required: true,            // 필수 여부
  example: 1                 // 예시 값
})

 

* 종합 예시

@ApiTags('posts')
@Controller('posts')
export class PostsController {
  @Get()
  @ApiOperation({
    summary: '게시글 검색',
    description: '조건에 맞는 게시글 목록을 검색합니다.'
  })
  @ApiHeader({
    name: 'Authorization',
    description: '인증 토큰',
    required: true
  })
  @ApiQuery({
    name: 'keyword',
    description: '검색어 (제목, 내용 포함)',
    required: false
  })
  @ApiQuery({
    name: 'status',
    enum: ['DRAFT', 'PUBLISHED', 'DELETED'],
    description: '게시글 상태 필터'
  })
  search(
    @Query('keyword') keyword?: string,
    @Query('status') status?: string
  ) {
    // 검색 로직
  }

  @Get(':id/comments/:commentId')
  @ApiOperation({
    summary: '특정 게시글의 댓글 조회',
    description: '게시글에 속한 특정 댓글의 상세 정보를 조회합니다.'
  })
  @ApiParam({
    name: 'id',
    description: '게시글 ID'
  })
  @ApiParam({
    name: 'commentId',
    description: '댓글 ID'
  })
  getComment(
    @Param('id') postId: number,
    @Param('commentId') commentId: number
  ) {
    // 댓글 조회 로직
  }
}