API 문서화의 딜레마 Swagger vs Postman
1. API 문서화, 왜 중요한가?
2. Swagger와 Postman의 특징 비교
3. 기존 문서화 도구 사용 경험에 대한 느낀점
4. 최종 결론
1. API 문서화, 왜 중요한가?
'API를 문서화 한다' 라는 것은 API의 사양, 요청, 응답 구조를 명확히 정의한 문서를 공유하는 것이라 할 수 있다. API 문서화는 마치 대학교 과제 같은 존재라고 생각한다. 하지만 API 문서화를 함으로써 팀 간의 협업 속도 증가, 변경 관리 및 유지보수가 용이하고, 문서를 기반으로 테스트가 가능하므로 효율성이 높다고 생각한다. 이 글에서는 Swagger와 Postman 중 어떤 도구를 선택해야 효율적일지 고민하는 글을 작성해보려고 한다.
2. Swagger와 Postman의 특징 비교
Swagger
장점
- 코드와 API 명세가 동기화되어 API 변경 시 문서도 자동으로 업데이트 된다.
- RESTful API 표준에 맞춰 명확하게 문서를 생성한다.
단점
- (라라벨의 경우) 컨트롤러 코드에 어노테이션을 추가해야 해서 코드 가독성이 떨어질 수 있다.
- 초기 설정 및 사용법 학습에 시간이 필요할 수 있다.
- (라라벨의 경우) API가 복잡할수록 주석 및 어노테이션이 길어져 관리가 어려워질 수 있다.
Postman
장점
- 별도의 코드 수정 없이 독립적으로 API 문서를 작성하고 테스트가 가능하다.
- 다양한 환경 설정 및 API 테스트 기능을 제공한다.
- 팀원 간 API 요청/응답 공유 및 협업에 용이하다.
단점
- API와 문서 간 동기화를 별도로 관리해야 한다.
3. 기존 문서화 도구 사용 경험에 대한 나의 느낀점
라라벨로 API 문서를 만들어야 하는 상황이 생겨 라라벨 코드에 OA어노테이션 주석으로 swagger 문서를 작성하면서 느낀 것들이 있는데,
1. Swagger 어노테이션을 컨트롤러에 추가하는 방식은 코드 가독성을 떨어뜨리지만, 작성 과정에서 API 요청 및 응답을 점검할 수 있다는 점이 좋았다.
2. 팀원과의 협업에 용이했다.
3. 처음에는 문서화가 어렵게 느껴졌지만, 반복적으로 사용하면서 익숙해졌다.
하지만 Postman에서 놓칠 수 없는 기능은 Postman은 독립적인 인터페이스로 API 테스트와 문서화 작업이 분리되어 있어 코드의 복잡도를 줄일 수 있다는 점(라라벨 기준)을 포기할 수 없었다.
4. 최종 결론
이 주제에 대해 개발 팀장님과 고민을 많이 했었는데, 결론적으로는 Swagger를 유지하기로 했다.
기존에 Swagger 사용 경험이 있고,API 설계와 구현이 동시에 이루어지는 환경에서 작업하고 있었기 때문에 Swagger가 더 적합했다. 문서화 도구 선택하기 위한 기준은 도구의 기능뿐만 아니라, 팀원들과의 협업, 사용 편의성이라고 생각한다.
앞으로도 이러한 논의를 통해 더 나은 방법과 도구를 지속적으로 탐색할 수 있는 개발자가 되길!