본 포스팅은 패스트캠퍼스 환급 챌린지 참여를 위해 작성하였습니다.
커리어 성장을 위한 최고의 실무교육 아카데미 | 패스트캠퍼스
성인 교육 서비스 기업, 패스트캠퍼스는 개인과 조직의 실질적인 '업(業)'의 성장을 돕고자 모든 종류의 교육 콘텐츠 서비스를 제공하는 대한민국 No. 1 교육 서비스 회사입니다.
fastcampus.co.kr
0427 일
학습 내용 정리
[Class 01]Part 27 .Swagger 다큐멘테이션
다큐멘테이션 구현하기
Swagger 세팅하기수강후기
오늘은 NestJS 수업에서 Swagger 다큐멘테이션을 직접 구현해보았다.
기존에는 API를 테스트할 때 매번 Postman을 켜고, 주소를 입력하고, Body나 Header를 설정한 다음 요청을 보내는 방식으로 작업했는데, Swagger를 적용하고 나니까 이젠 Postman 없이도 브라우저 상에서 실시간으로 API를 확인하고 테스트할 수 있어서 훨씬 편리해졌다. 특히 API 명세가 자동으로 생성된다는 점이 정말 매력적이었다.
수업 중 작성한 코드는 DocumentBuilder를 사용해 문서 제목(넷플릭스), 설명(NestJS 프로젝트), 버전(1.0)을 설정하고, SwaggerModule.createDocument()를 통해 실제 문서를 생성한 다음, SwaggerModule.setup('doc', app, document)를 통해 /doc 경로에 Swagger UI를 띄우는 방식이었다.
초기 설정이 생각보다 간단했고, 몇 줄의 코드만으로 프로젝트 전체 API를 직관적으로 볼 수 있게 된다는 점이 굉장히 효율적이라고 느꼈다. 또, 나중에 기능이 추가되거나 변경될 때도 Swagger 문서가 코드 기반으로 자동 반영되기 때문에, API 명세를 별도로 관리할 필요 없이 항상 최신 상태를 유지할 수 있다는 점도 큰 장점이라고 생각했다.
ValidationPipe를 적용한 상태에서도 Swagger가 입력값 제약사항(예: 필수값, 타입 등)을 명시해주기 때문에, 클라이언트 개발자가 별도로 서버에 물어보지 않아도 요청 포맷을 정확히 이해할 수 있게 된다.
또한 API 버전 관리 기능(VersioningType)과도 연동할 수 있어서, 실제 운영 환경에서도 RESTful API 버전별 관리가 훨씬 수월해질 것으로 보인다.
실습을 해보면서 Swagger가 단순한 테스트 도구를 넘어, 프로젝트 전반의 품질을 높이는 역할을 해준다는 걸 깨달았다. API 문서가 잘 정리된 프로젝트는 협업 효율이 높고, 이후 유지보수 시에도 훨씬 안정적인 작업이 가능하다. 나중에 프론트엔드와 연동하거나, 팀 프로젝트를 진행할 때에도 Swagger를 적극 활용해서 작업 시간을 줄이고 소통을 매끄럽게 하고 싶다.
오늘 배운 Swagger 설정 방법은 앞으로 NestJS 프로젝트를 시작할 때 기본 세팅으로 추가할 정도로 필수 기능이라고 느껴졌다.
처음에는 다큐멘테이션이라고 해서 단순히 문서만 만든다고 생각했지만, 막상 적용해보니 개발, 테스트, 협업 모든 측면에서 실질적인 이점이 크다는 것을 확실히 알게 된 수업이었다.
사진
