A. 배경
이 글은 ERD와 API를 설계할 때 어떤 툴을 사용하면 협업에 더 효과적일지 고민하는 분들을 위한 글입니다. 아래는 제가 실제 프로젝트에서 사용해본 여러 툴에 대한 주관적인 경험과 생각을 정리한 내용입니다. 혹시 더 좋은 툴을 사용해보셨다면 댓글로 추천해주시면 직접 사용해보고 후기를 업데이트하겠습니다.
ERD
1. dbdiagram.io 🔗
쿼리로 그리는 ERD
처음 프로젝트에서 ERD를 그려야 했을 때, dbdiagram.io를 사용해봤어요. 이 툴의 가장 큰 특징은 마우스로 박스를 끌어다 놓는 방식이 아니라, 쿼리 문법으로 ERD를 그릴 수 있다는 점입니다. 예전에 SQL 쿼리 실습을 조금 해본 덕분에, 오히려 이런 방식이 더 편하게 느껴졌고, 실제로 테이블 구조를 쿼리로 직접 써보니까 SQL에 더 익숙해지는 효과도 있었습니다.
예쁘고 깔끔한 UI
dbdiagram.io는 UI가 깔끔하고 예쁘다는 점이 정말 인상적이었어요. 발표 자료(PPT)에 ERD를 넣을 때 캡처해서 쓰면 보기 좋은 결과물이 나옵니다.
다른 ERD 툴들에 비해 색감, 폰트, 다이어그램 정렬이 잘 되어 있어서, 결과물을 공유할 때 뿌듯함이 남아요. (UI 느낌이 제 취향이기도 했고요.)
협업할 땐 아쉬운 점도...
아쉬운 점도 있었습니다. 여러 명이 동시에 쿼리 문서를 수정할 수 없어서 협업에는 불편했습니다.
실시간 동기화가 지원되지 않다 보니(유료 버전에서는 실시간 가능), 한 명이 쿼리를 작성하고 다른 팀원들은 그걸 보면서 피드백만 주는 식으로 진행했어요.
실시간으로 같이 수정하고 싶은 순간이 많았는데, 이 부분은 확실히 아쉬웠던 기억이 남습니다. 그래서 다른 툴을 찾아보는 계기가 되기도 했어요.
정리
정리하자면:
쿼리 기반이라 SQL에 더 익숙해질 수 있고, 결과물이 예뻐서 발표 자료에 넣기 좋았던 툴!
다만, 여러 명이 동시에 작업하는 협업에는 조금 불편함이 있었던 점은 참고하면 좋을 것 같습니다.
2. erdcloud 🔗
처음에는 dbdiagram 같은 쿼리 기반 툴을 써봤지만, 코드나 쿼리 입력이 익숙하지 않아서 금방 한계에 부딪혔습니다. 그러다 ERDCloud를 알게 되었고, 아이콘을 클릭해서 테이블을 만들고, 관계도 선으로 연결하는 방식이 정말 직관적이어서 금방 적응할 수 있었습니다.
직관적인 아이콘
- 테이블과 관계를 마우스로 클릭하고 드래그해서 만들 수 있습니다.
- 테이블 안에 컬럼도 칸을 클릭해서 입력만 하면 바로 추가됩니다.
협업 기능
- TEAM 기능으로 팀을 만들고, 이메일로 팀원 초대가 가능합니다.
- 댓글 기능이 있어 팀원들과 의견을 주고받을 수 있습니다.
실시간 동기화
- 팀원이 동시에 작업을 해도 변경 사항이 바로 반영되어 협업에 더 좋습니다. (무료에요!!)
사용하면서 느낀 아쉬운 점
- 테이블에 값을 입력할 때 엔터를 꼭 눌러야 저장됩니다. 처음엔 조금 헷갈릴 수 있어요.
- 화면 오른쪽에 광고가 떠서 집중이 잘 안 될 때가 있습니다.
- dbdiagram에 비해 디자인이나 일부 기능이 살짝 구식처럼 느껴질 때가 있습니다. 그래도 기본적인 기능은 충분히 쓸 만합니다.
복잡한 설치나 어려운 코딩 없이, 그림 그리듯이 데이터베이스 구조를 만들고 팀원과 실시간으로 협업할 수 있다는 점이 ERDCloud의 가장 큰 매력이라고 생각합니다.
API 명세서
1. Swagger
Swagger는 API를 설계하고 문서화하는 오픈소스 도구입니다. 복잡한 API 구조를 쉽게 설명하고, 팀원들과 효과적으로 소통하며, 실제로 API가 어떻게 동작하는지 직접 테스트할 수 있도록 도와줍니다.
자동 문서화
- Swagger는 코드 기반으로 API 문서를 자동 생성해줍니다.
- 서버 코드에서 요청과 응답을 처리하는 부분에 Swagger 관련 코드를 추가하면, 별도의 문서 작업 없이 API 명세가 자동으로 문서화되어 웹 페이지 형태로 확인할 수 있습니다.
인터랙티브한 테스트
- Swagger 코드를 서버에 작성하고 서버 로직을 구현한 뒤에는, 자동으로 생성된 문서화 페이지에서 각 API를 직접 테스트해볼 수 있습니다.
- 개발자들은 응답 결과나 오류 여부를 즉시 확인할 수 있어 개발 효율성이 높아집니다.
표준화 형식
- Swagger는 OpenAPI라는 표준을 따릅니다.
- 이 덕분에 다양한 언어와 프레임워크에서 폭넓게 사용할 수 있으며, 범용적으로 가장 널리 쓰이는 API 문서화 방식 중 하나입니다.
개인적 생각
Swagger는 코드 기반으로 문서를 작성하는 도구이기 때문에, 프로젝트 개발 환경이 어느 정도 갖춰진 후에 도입하는 것이 적합하다고 생각합니다. 그래서 첫 프로젝트를 진행하는 분들에게는 추천하지 않습니다.
서버 코드에서 언제든지 문서를 수정할 수 있기 때문에, API 명세의 주도권이 백엔드 개발자에게 치우치는 느낌이 있습니다. 저는 API 명세서는 중립적으로 관리되는 것이 가장 이상적이라고 생각하기 때문에, 프로젝트 초기에 Swagger를 도입하는 데에는 다소 망설임이 있습니다.
프론트엔드 개발자가 Swagger 문서화 페이지에 접근하려면 서버가 배포된 상태여야 하는데, 첫 프로젝트에서는 서버 설계와 배포 자체가 쉽지 않을 수 있습니다. 저 역시 개발을 시작할 때 바로 서버 세팅과 자동 배포 파이프라인을 구축하는 편이지만, 초보자에게는 이러한 과정이 부담스러울 수 있다고 생각합니다.
따라서 첫 프로젝트를 진행하는 분들은 Swagger 같은 자동화 도구보다는 직접 API 문서를 작성해보는 경험을 쌓는 것이 더 도움이 될 것이라 생각합니다.
2. Postman & Apidog
Postman과 Apidog은 API를 쉽게 테스트하고 관리할 수 있게 도와주는 무료 도구입니다. 복잡한 코드 없이도 API 요청을 만들고, 응답을 확인하며, 팀원들과 결과를 공유할 수 있습니다.
쉬운 API 테스트
- UI 기반으로 GET, POST, PUT, DELETE 등 다양한 HTTP 요청을 손쉽게 만들 수 있습니다.
- 요청에 필요한 파라미터, 헤더, 바디 등을 직접 입력하고, 클릭 한 번으로 응답을 바로 확인할 수 있습니다.
- 복잡한 코드 작성 없이도 UI 기반으로 API가 어떻게 동작하는지 쉽게 실험해볼 수 있습니다.
요청과 응답 기록
- 보낸 요청과 받은 응답이 자동으로 기록되어, 언제든지 다시 확인하거나 재사용할 수 있습니다.
- 요청을 저장해두고, 나중에 반복적으로 테스트할 수 있습니다.
팀 협업 지원
- 요청이나 컬렉션을 팀원과 쉽게 공유할 수 있습니다.
- API 문서를 자동으로 생성해주어, 팀원들과의 소통이 쉬워집니다.
개인적 생각
Postman과 Apidog은 문서를 자동으로 생성해주지는 않지만, UI 기반으로 API의 엔드포인트와 요청 값을 입력해 직접 API를 테스트할 수 있는 툴입니다.
이런 방식으로 테스트를 진행하면, 요청과 응답 기록이 자동으로 저장되어 워크스페이스에 초대한 팀원들과 테스트 결과를 함께 관리할 수 있습니다.
특히 서버가 아직 배포되지 않은 상황에서도, API만 동작하는 환경이 준비되어 있다면 프론트엔드 개발자가 워크스페이스에 초대되어 직접 테스트 결과를 확인할 수 있습니다.
이 과정에서 API 명세 문서를 보는 것보다 실제 요청과 응답을 직접 확인하는 것이 이해에 훨씬 도움이 되는 경우가 많습니다.
Postman vs. Apidog: 협업 인원 차이
Postman과 Apidog은 기능적으로 유사하지만, 가장 큰 차이점은 무료로 협업할 수 있는 인원 수입니다.
Postman은 무료 플랜에서 최대 3명까지 협업이 가능하지만, Apidog은 4명까지 지원합니다.
학교 프로젝트처럼 4명 내외의 팀을 구성하는 경우가 많기 때문에, 이런 상황에서는 Apidog이 특히 유용한 선택이 될 수 있습니다.
3. Notion
저는 노션으로 할때는 이런식으로 표 템플릿을 만들어서 API를 각각 정의하고 그 안의 페이지에서 세부적인 요청과 응답에 필요한 값을 세부적으로 적어줍니다.
높은 자유도와 유연성
다양한 형식(텍스트, 표, 코드, 이미지, 다이어그램 등)으로 API 명세를 자유롭게 작성할 수 있습니다. 프로젝트에 맞는 구조를 직접 설계할 수 있어, 팀의 스타일에 맞게 문서를 꾸밀 수 있습니다.
실시간 협업과 공유
여러 명이 동시에 문서를 작성하고, 변경 이력을 쉽게 추적할 수 있습니다. 워크스페이스 내에서 팀원들과 손쉽게 공유하고, 의견을 주고받으며 협업이 가능합니다.
템플릿과 데이터베이스 활용
반복되는 API 명세 형식을 템플릿으로 만들어 일관성 있는 문서화를 할 수 있습니다. 데이터베이스 기능을 이용하면 API 목록을 표 형태로 관리하거나, 필터·정렬이 가능합니다.
비용
저는 학교 계정을 통해서 계정이 업그레이드 된 상태로 사용을 하고 있어서 블록 개수와 같은 게 지장 없이 워크스페이스를 많이 많이 사용할 수 있어 편하게 사용하고 있습니다.
나의 생각
Notion으로 API 명세서를 작성하면 문서의 자유도가 매우 높아서, 프로젝트 상황이나 팀의 스타일에 맞게 원하는 방식으로 정보를 구성할 수 있습니다. 텍스트, 표, 코드 블록, 이미지 등 다양한 요소를 자유롭게 활용할 수 있고, 템플릿 기능을 이용하면 반복적인 작업도 일관성 있게 효율적으로 진행할 수 있습니다. 여러 API 문서를 작성할 때 같은 형식의 템플릿을 적용하면, 팀원 누구나 쉽게 이해하고 관리할 수 있는 구조를 만들 수 있다는 점이 큰 장점입니다.
특히 Notion은 코드에 의존하지 않고, 진짜 문서 기반으로 명세서를 작성하기 때문에 특정 개발자에게 치우치지 않고 팀 전체가 동등하게 의견을 반영할 수 있습니다. 제가 중립성을 강조하는 이유는, Swagger 같은 코드 기반 자동화 도구를 사용할 경우 실제로 백엔드 개발자가 코드를 수정하면서 API 명세를 임의로 바꾸거나, 형식보다는 개인의 편의에 따라 문서를 변경하는 경우를 종종 봤기 때문입니다. 이런 상황에서는 프론트엔드나 다른 팀원이 변경 사항을 바로 알기 어렵고, 커뮤니케이션이 단절되는 문제가 생길 수 있습니다.
반면 Notion에서는 수정 이력 추적과 알림 시스템이 잘 되어 있어서 누가 언제 어떤 내용을 변경했는지 쉽게 확인할 수 있습니다. 문서가 수정되면 팀원들에게 자동으로 알림이 가고, 변경 이력을 통해 이전 상태로 되돌릴 수도 있습니다. 또한 댓글이나 멘션 기능을 통해 의견을 주고받으며 실시간으로 협업할 수 있기 때문에, 팀 전체가 명확하게 소통하고 중립적이고 투명한 방식으로 API 명세를 관리할 수 있습니다.
C. 마무리
이번 글에서는 ERD와 API 명세서 설계 시 협업에 도움이 되는 다양한 툴에 대해, 실제 사용 경험을 바탕으로 주관적인 생각을 정리해보았습니다. 여러 툴들이 존재하고, 각 툴마다 장단점이 다르니 프로젝트 상황에 맞게 선택하는 것이 중요합니다. 특히 첫 프로젝트를 준비하는 분들에게는 상황을 파악하고 툴을 선정하는 데 어려움이 있을 거라고 생각하여, 조금이나마 도움이 되었으면 하는 마음으로 직접 써본 툴 위주로 간단하게 소개해드렸습니다.
툴의 개념적인 설명만으로도 분량이 많아질 수 있어서, 이번에는 툴 소개에 집중해 하나의 글로 정리했습니다. 실제로 프로젝트를 하다 보면 자신에게 딱 맞는 툴을 찾는 과정이 쉽지 않을 수 있습니다. 그래서 저처럼 여러 툴을 직접 사용해보며 느꼈던 점들을 공유하고자 했습니다. 만약 이 글에서 마음에 드는 툴이 있다면, 공식 홈페이지나 다른 사용 후기 등을 참고해보시면 사용법은 금방 익히실 수 있을 거라 생각합니다.
상황에 따라 더 좋은 툴이 있을 수도 있으니, 혹시 추천하고 싶은 툴이 있다면 댓글로 알려주시면 저도 사용해보고 후기를 업데이트하겠습니다. 앞으로도 다양한 협업 도구와 경험을 나누는 글을 계속해서 남겨보겠습니다.
이번 글은 저의 주관적인 생각이 많이 담겨서 내용이 조금 길어진 것 같아요. 읽어보시고 제 생각과 다른 점이 있다면 댓글로 의견 남겨주세요. 함께 더 좋은 방향을 찾아가고 싶어요!
