데이터 분석 프로젝트 – Swagger 덕분에 살았다

이 글은 2022년 10월 3일과 23일, 벨로그에 처음 작성했던 글을 보완한 버전입니다.
팀 프로젝트를 준비하시는 분들께 작은 도움이 되기를 바랍니다.

 

협업과 API (출처: GPT 이미지 생성)

시작: 3주간의 데이터 분석 프로젝트

 

이번 프로젝트는 3주 동안 진행된 데이터 분석 웹 프로젝트였다.

나는 팀에서 백엔드를 담당하게 되었는데, 팀원 5명 중 백엔드 개발자는 나 혼자였다.

 

혼자서 API 설계, 인프라 구성, 문서화, 테스트 지원까지 모두 맡아야 하는 상황.

사실 처음엔 많이 부담스러웠다.

웹에서 파이썬 기반 데이터 분석 기능을 어떻게 붙일지도 막막했고, 시간이 정말 부족해 보였다.

 

괜히 “Swagger를 써보겠다”고 팀원들에게 호기롭게 말해버린 것도 살짝 후회가 되었다.

그땐 몰랐다.

Swagger가 이번 프로젝트를 살릴 열쇠가 될 줄은.

 

---

 

Swagger 세팅, 쉽지 않았지만 탁월했다

사실 Swagger는 단순히 ‘API 문서 도구’로만 생각했었는데,

이번에 써보니 그 이상이었다.

 

초반에 Swagger 세팅은 약간 삽질의 연속이었다.

FastAPI에서 기본으로 제공하는 Swagger UI는 정말 편했지만,

팀에서 요구하는 API 형식, 응답 예시, 오류 코드 등을 세세하게 문서화하는 부분은 직접 신경을 써야 했다.

 

처음엔 ‘이거 시간 낭비 아닌가’ 싶었지만,

프로젝트 중반부터 Swagger가 진가를 발휘하기 시작했다.

 

프론트엔드 개발자들이 내 API를 사용할 때,

Swagger 문서 덕분에 따로 질문이 거의 없었다.

 

심지어, 프론트에서 “이 API 왜 이러죠?“라고 물어보기도 전에,

Swagger에서 응답 형식과 샘플 값을 바로 확인하고 스스로 해결하는 모습을 보면서

‘진짜 잘 썼다’는 생각이 들었다.

 

---

 

Swagger가 해결해 준 실제 사례

 

한 번은 프론트엔드 쪽에서 데이터를 요청할 때 GET/POST 메서드 혼동으로 문제가 발생했다.

예전 같았으면 채팅이나 미팅으로 일일이 설명하고, 수정 요청을 했을 텐데,

이번엔 Swagger에서 바로 API 메서드와 파라미터 설명을 확인하고 바로 수정하시더라.

 

또 다른 예는, API의 응답 필드 중 선택적으로 제공되는 값이 있었는데,

Swagger에 ‘nullable’ 처리와 예외 케이스를 잘 기입해 두었던 덕분에

프론트엔드에서 ’이거 왜 null이죠?’라는 질문도 없었다.

 

이런 식으로 Swagger가 개발자 간의 ‘불필요한 질문’을 줄여줬고, 소통 비용을 크게 낮춰줬다.

결국, 백엔드와 프론트 간의 실시간 피드백 속도가 빨라졌고, 이게 정말 효율적이었다.

 

---

 

백엔드 혼자서도 할 수 있다

 

이번 프로젝트를 통해,

혼자 백엔드를 맡아도 생각보다 안정적으로 프로젝트를 끌고 갈 수 있다는 자신감을 얻었다.

 

Swagger, FastAPI, Docker 등 기존에 알고 있었지만 ‘제대로’ 써본 적 없던 기술을 실전에서 적용해 보니

문서화, 테스트, 협업까지 한 번에 경험할 수 있었다.

 

시간이 부족하다는 핑계로 문서를 소홀히 하거나,

‘코드만 돌아가면 된다’는 태도를 가졌다면

아마도 이번 프로젝트는 훨씬 더 힘들었을 것이다.

 

오히려 Swagger를 통해 미리 API를 설계하고 문서화하는 과정이, 개발 속도를 늦추는 게 아니라 ‘더 빠르게’ 만들어준다는 걸 직접 느꼈다.

 

다음 프로젝트에서도 Swagger는 필수다.

 

---

 

사이드: 프론트 공부, 도커 복습

 

이번 프로젝트를 계기로 프론트엔드 기술도 잠깐 맛봤다.

프론트 쪽은 리액트와 타입스크립트를 사용했는데,

타입스크립트는 지금 단계에서 깊이 파고들지 않고, 흐름을 이해하는 정도로 넘어갔다.

 

빠르게 진행되는 협업에서는 타입스크립트의 엄격함이 오히려 발목을 잡을 수도 있다는 얘기도 들었기에

이번엔 과감히 ‘안 보는 전략’을 택했다. 물론 장기적으로는 공부할 필요가 있다.

 

또, 도커도 이번에 복습했다.

컨테이너 기반 개발 환경을 구성해보려고 했지만,

시간과 팀 상황을 고려해 이번에는 단순한 로컬 서버로 진행했다.

 

다음엔 도커까지 잘 연동해보고 싶다.

 

---

 

회고: 결국, 소통이 전부다

 

3주간의 프로젝트가 순식간에 끝났다.

처음엔 ‘매일 기록하자’고 다짐했지만,

현실은 Day 1 포스팅 이후, Day 21이 마지막 기록이 되어버렸다.

 

정말 바빴다. 하지만, 그 바쁨 속에서 확실히 느낀 게 있다.

 

결국 협업에서 가장 중요한 건 ‘소통’이다.

그리고 그 소통을 가장 잘 도와준 건 Swagger였다.

 

Swagger를 잘 쓰는 것, 그리고 문서를 빠르게 공유하는 것.

이 두 가지만으로도 협업에서 발생할 수 있는 대부분의 문제를 미리 줄일 수 있었다.

 

다음 프로젝트에서는 더 빠르게, 더 정확하게, 더 잘 기록하고 싶다.

이 글도 그 기록 중 하나로 남긴다.

 

🔍 참고

• Swagger 세팅 시 API 예제 응답, 오류 코드, nullable 필드를 명확히 작성하면 실무에서 정말 도움이 됩니다.
• 프론트 협업 시 메서드(GET/POST) 혼동, 응답 필드 누락 등은 Swagger에서 미리 검증 가능하니 적극 활용하는 걸 권장합니다.
• 시간 없을 때 도커는 ‘필수’는 아니지만, 장기적으로는 개발 환경 통일에 도움이 되니 가능하면 준비해두면 좋습니다.