실전 프로젝트 트러블 슈팅🚀
실전 프로젝트를 진행하며 디자이너님 그리고 FE분들과의 원활한 소통을 위하여 Swagger를 도입, 적용해보았다. 추후 트러블슈팅으로 사용할 수 있을 것이라 판단되어 기록해두고자 한다.
Swagger의 도입
문제상황
처음에는 노션 팀 페이지를 통하여 API 명세서를 작성, 이용하고 있었습니다. 하지만 프로젝트를 진행할수록 아래와 같은 문제가 발생하기 시작하였습니다.
- API 명세서의 가독성 저하
개발해나가는 API의 양이 점차 증가함에 따라 명세서에 기록되는 API들도 많아졌고 주고 받는 데이터도 증가, 복잡해짐으로 API 명세서 자체의 가독성이 저하되는 문제가 발생하였습니다.
- 의사소통 문제
FE, BE 개발자 모두 API 명세서와 관련하여 소통에 많은 시간을 할애하게 되었습니다. API 명세서 자체의 가독성이 떨어지다보니 수정 사항이 발생하여 이에 대해 팀원들에게 설명하는데 많은 시간을 소모하게 되었으며, 수정사항을 공유하지 않아 작업시간이 증가하거나 팀원 간의 트러블로 번지는 경우도 발생하였습니다.
원인
팀원들간의 원활한 소통을 위하여 필수적인 API 명세서의 중요성을 간과하여 충분히 고민해보지 않고 그간 해왔던 방식(노션 페이지에 작성)을 실전 프로젝트에 그대로 적용했기에 발생한 문제였습니다.
그간 해왔던 프로젝트(미니, 클론 프로젝트)들 보다 팀원 수도 많아졌으며 서비스의 규모도 커졌기에 보다 정확하고 효과적인 API 명세서가 필요했던 시점이었습니다.
해결
어떻게하면 보다 효과적으로 개발자 팀원뿐만 아니라 디자이너까지도 API 명세서를 활용할 수 있을까에 대해 고민을 하던 중, 현업에서는 Swagger 프레임워크를 사용하여 API 명세서를 구성한다는 사실을 알게되어 Swagger에 대한 추가 조사를 바탕으로 팀원들과 논의, 긍정적인 반응을 바탕으로 도입하게 되었습니다.
1. Swagger 적용
Swagger 라이브러리의 의존성을 추가해주었습니다. 이것만으로도 Swagger 사용이 가능했지만 추가적인 소통없이 Swagger Ui만 보고도 API에 대해 파악할 수 있을 정도로 상세하게 Swagger Ui를 구성하고 싶었습니다.
2. Swagger Ui 상 Controller 및 각 메소드에 대한 설명 추가
각 컨트롤러 별 @Api, @ApiOperation 어노테이션을 추가하여 각각의 컨트롤러 및 메소드가 어떤 역할을 하는지에 대해서 명시해주었습니다. 이를 바탕으로 Swagger Ui만 보아도 해당 Controller가 그리고 또 API가 어떤 기능을 수행하는지 한 눈에 파악할 수 있게 되었습니다.
3. 프로젝트에 대한 기본 설명 추가(SwaggerConfig)
프로젝트에 대한 정보를 담고 기본적인 설정을 해주기 위하여 Swagger 설정 파일, SwaggerConfig 파일을 작성해주었습니다.
4. Swagger Ui에서 Pageable이 적용된 API 문제
기본적인 설정을 마쳤지만 Swagger Ui에서 일부 제대로 사용할 수 없는 API가 있었습니다. 그중 첫번째가 바로 Pagination이 적용된 API들이었습니다.
FE에서 무한스크롤을 적용하기 위하여 BE 단에서 Pageable을 적용하여 Param 값으로 page(key), pagenumber(value) 형태로 넘겨주기로 약속하고 코딩하였었는데 Swagger Ui 상에서는 pageNumber라는 Default key가 적용되어 있었고 Ui 내에서는 변경이 불가했습니다.
이 문제를 해결하기 위하여 SwaggerConfig에 해당 부분에 대한 설정을 추가하였습니다.
5. 로그인이 필요한 API 문제
프로젝트 멍냥에는 로그인이 필요한 API들(상품 등록, 수정, 삭제 등)이 존재하였고, Swagger를 보다 효과적으로 사용하기 위해서는 Swagger Ui 내에서 해당 API들도 테스트 해볼 수 있어야 한다고 판단하였습니다. 하지만 기존 로직상으로는 로그인을 하면 JWT 토큰이 부여되어 이를 바탕으로 로그인 여부를 파악하였었는데 기존에 설정해두었던 Swagger 설정 상으로는 이러한 부분이 불가하였고 추가적인 설정이 필요하였습니다.
전역 AuthoriztionScope를 사용해 JWT SecurityContext를 구성하였으며 현재 프로젝트 내에서 'Authorization'이라는 이름으로 토큰을 사용하고 있었기에 ApiKey를 바탕으로 해당 key 값을 설정해주었습니다.
6. 설정이 끝난 Swagger Ui
결과
Swagger 도입을 바탕으로 FE와 BE 개발자 팀원뿐만 아니라 디자이너 팀원까지도 API를 테스트 해보고 원활한 소통이 가능해졌습니다.
기존에는 BE에서 먼저 개발한 API를 FE에서 적용시킬 때, 해당 기능을 개발한 BE 개발자가 Request 값이나 Response 값등을 노션페이지에 작성해두었던 API 명세서를 바탕으로 설명하는 불필요한 과정이 필요했습니다. 하지만 Swagger의 도입으로 FE에서 자체적으로 기능별 API를 테스트 해볼 수 있었고 디자이너 팀원까지도 이 부분을 가능케 했습니다.
어떤 API 명세서를 사용하냐가 프로젝트의 진행 속도에 지대한 영향을 미칠 수 있다는 것을 알 수 있었고 API 명세서 그 자체의 중요성에 대해서도 다시 한 번 깨닫는 경험이었습니다.
'✍️개발로그' 카테고리의 다른 글
| 실전프로젝트 5주차(Query 메서드 리팩터링 feat.QueryDSL) (0) | 2022.09.23 |
|---|---|
| 20220909_실전 프로젝트 14일차(최근 조회한 상품 목록) (0) | 2022.09.09 |
| 220830_실전프로젝트 8일차(feat.Item 수정부분 트러블슈팅🚀) (0) | 2022.09.03 |
| 220829_실전프로젝트 4일차 (0) | 2022.08.29 |
| 20220823_클론코딩(항해인사이드) 5일차 (0) | 2022.08.23 |