패스트캠퍼스 환급챌린지 56일차 : 코드팩토리의 백엔드 아카데미 : 한 번에 끝내는 NestJS 패키지 - 기초부터 MSA까지 강의 후기

본 포스팅은 패스트캠퍼스 환급 챌린지 참여를 위해 작성하였습니다.

https://bit.ly/4hTSJNB

🚨5월 1일 00시 강의 가격 대폭 인상! | 패스트캠퍼스

04 29 화

학습 내용 정리

[Class 01]Part 27 .Swagger 다큐멘테이션

Ch 1. 다큐멘테이션 구현하기

ApiProperty Annotation 알아보기

    @IsNotEmpty()
    @IsNumber()
    @ApiProperty({
        description: '감독 객체 ID',
        example: '1',
    })
    directorID: number;

               이렇게 사용

ApiOperation 알아보기

              각 엔드포인트 controller에 @ApiTags('endpoint') 작성

 

ApiHideProperty 알아보기

 

docs는 즉, swagger는 front 와 backend의 의사소통이 없음을 기준으로 적어놓는게 아닌

복잡한 로직에 관해서만 서술하는걸 추천한다

수강후기

오늘은 Swagger를 활용한 다큐멘테이션 구현에 대해 학습하는 시간을 가졌습니다. 먼저 @ApiProperty 애너테이션을 통해 각각의 DTO 속성에 대해 명확한 설명(description)과 예시(example)를 추가하는 방법을 배웠습니다. 이를 통해 API 문서가 더욱 직관적으로 변하고, 실제 프론트엔드 개발자나 외부 사용자들이 API를 쉽게 이해할 수 있다는 점을 느꼈습니다. 단순히 타입만 명시하는 것이 아니라, 필수 여부(@IsNotEmpty, @IsNumber)와 함께 API 명세를 동시에 제공하는 구조가 매우 인상적이었습니다.

또한, @ApiOperation과 @ApiTags를 이용해 엔드포인트별로 기능을 분류하고 설명하는 방법을 배웠습니다. 이를 통해 Swagger 문서가 단순한 API 리스트가 아니라, 기능별로 구조화된 명확한 문서로 완성된다는 점을 깨달았습니다. 특히 각 컨트롤러 상단에 @ApiTags를 선언하여 API가 어떤 범주에 속하는지 분리하는 것은 실무에서도 바로 적용할 수 있을 만큼 실용적인 팁이었습니다.

@ApiHideProperty를 이용해 내부적으로만 사용하는 속성은 Swagger 문서에 노출시키지 않는 방법도 알게 되었습니다. 이렇게 필요한 정보만 깔끔하게 보여주고, 불필요한 정보는 숨기는 세심한 접근이 Swagger 다큐멘테이션의 완성도를 높인다는 것을 알게 되었습니다.

가장 인상 깊었던 부분은 Swagger는 무조건 백엔드 API를 모두 설명하는 데 사용하는 것이 아니라, 프론트와 백엔드의 명확한 커뮤니케이션이 필요한 복잡한 로직에 집중해서 작성하는 것이 효율적이라는 조언이었습니다. 이 부분은 그동안 Swagger를 무조건 전체 API를 다 문서화해야 한다고 생각했던 저에게 매우 신선한 시각이었습니다. 실무에서는 정말 필요한 부분을 중심으로 문서를 작성하는 것이 오히려 협업 효율을 높인다는 사실을 배울 수 있었습니다.

오늘 배운 Swagger 다큐멘테이션 작성법은 단순한 기술적 스킬을 넘어서, 협업과 커뮤니케이션을 고려한 프로페셔널한 API 설계 방법론을 익히는 소중한 시간이었습니다. 앞으로 실습 프로젝트나 실제 서비스 개발 시 Swagger를 제대로 활용하여, 사용자 친화적이고 명확한 API 문서를 작성하는 데 자신감을 가지게 될 것 같습니다.

사진

시작/종료

수강클립/결과물