협업에서 배운 API 공유의 중요성: 팀 프로젝트 실전 회고

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

온라인 팀 프로젝트 실전 경험을 통해 API 공유의 중요성을 배웠습니다. 협업에서 흔히 발생하는 문제와 API 명세 툴 Swagger의 활용법을 개발자의 시선으로 쉽게 정리했습니다.

 

 

---

 

협업, 그리고 API 공유에 대하여

 

이 글은 혼자 개발하던 제가 온라인 팀 프로젝트를 진행하며 직접 경험한 이야기입니다.

특히 API 공유의 중요성을 체감한 순간과 실전 팁을 공유합니다.

 

---

 

1. 예상과 다른 팀 프로젝트의 시작

 

처음 팀 빌딩을 할 때, 프론트엔드 지원자가 대부분일 줄 알았습니다.

하지만 팀원 6명 중 백엔드 지원자가 2명이나 있었고, 저는 프론트를 맡게 되었죠.

 

문제는 팀이 백엔드, 프론트엔드로 완전히 분리되어

서로 “알아서 개발”하는 방식으로 흘러갔다는 점이었습니다.

 

---

 

2. API 공유가 늦어진 대가

 

팀원 간 커뮤니케이션이 부족해,

프로젝트 2/3 시점이 되어서야 API가 공유되는 사태가 벌어졌습니다.

 

결국 프론트엔드 소스를 전면 수정해야 했고,

테스트도 뒤늦게 진행하는 비효율이 발생했습니다.

 

---

 

📌 협업 시 반드시 기억해야 할 것

 

• API 명세는 초기에 공유, 필수
• 기본 필드, 메소드명 등 명명 규칙을 초반에 확정
• Git 브랜치 전략을 단순하고 명확하게

 

이 기본만 지켜도 중복 작업을 크게 줄일 수 있습니다.

 

---

 

3. Git, 협업의 또 다른 핵심

 

당시 팀원 모두 Git 협업 경험이 많지 않았습니다.

저 역시 Git 충돌을 피하려고 내 소스를 계속 수동으로 맞추는 바람에,

개발 시간보다 소스 관리에 더 많은 시간을 쓰게 되었죠.

 

✅ 팁: 빠르게 진행해야 하는 팀 프로젝트라면,

풀스택 또는 공통 개발자가 먼저 commit & push 하고,

다른 팀원이 pull 받아서 이어가는 방식이 효율적입니다.

 

이런 협의만 있었어도 개발 시간이 훨씬 줄었을 겁니다.

 

---

 

4. Swagger, API 협업의 친구

 

이번 프로젝트에서는 Swagger를 사용하지 않았는데,

돌이켜보면 Swagger를 도입했다면 훨씬 수월했을 것 같습니다.

 

 

Swagger의 장점

 

• API 명세를 실시간으로 시각화
• 프론트, 백엔드가 동일한 테스트 UI 사용
• Postman 없이 브라우저에서 바로 테스트 가능

 

물론 단기 프로젝트는 오히려 부담일 수도 있지만,

중장기 프로젝트라면 초기부터 도입하는 것을 적극 추천합니다.

 

---

 

Swagger 간단 셋업 (Node.js 기준)

npm install --save swagger-jsdoc swagger-ui-express express nodemon

 

app.js 예시

import swaggerJsdoc from 'swagger-jsdoc';
import swaggerUi from 'swagger-ui-express';

const options = {
  definition: {
    openapi: '3.0.0',
    info: { title: 'API Example', version: '1.0.0' },
  },
  apis: [`${__dirname}/app.js`],
};

const swaggerSpec = await swaggerJsdoc(options);

app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));

👉 접속: http://localhost:포트번호/api-docs

 

---

 

🔗 참고 자료

 

• Swagger UI GitHub
• Swagger UI Express GitHub
• Swagger Hub
• 테스트용 API

 

---

 

5. 결론: 협업은 기술이자 커뮤니케이션

 

이번 팀 프로젝트를 통해 느낀 건

협업은 개발 기술 못지않게 커뮤니케이션 능력이 중요하다는 점이었습니다.

 

특히:

 

• API 공유
• Git 브랜치 전략
• 개발 일정 및 진행 상황 소통

 

이 세 가지를 초반에 제대로 합의하는 것이 효율적인 협업의 핵심입니다.

다음 프로젝트에서는 Swagger도 적극 도입해 보고,

더 즐거운 팀 개발을 경험해 보고 싶네요. 🙌