캐치딜 백엔드 개발이야기 : 문서화

 

• 소개

캐치딜 서비스는 2019년 10월부터 시작된 토이프로젝트의 일환으로, 같은 대학 주니어 대학생 3명이서 똘똘뭉쳐 제작된 프로젝트입니다.

캐치딜은 여러 플랫폼(뽐뿌, 클리앙 등)에 퍼져있는 핫딜특가 데이터를 Selenium 크롤링을 통해 데이터를 수집해서 보여주는 서비스입니다.

 

 

• 서론 : 문서화의 중요성

개발에 있어 문서화는 약속입니다.

 

1. 오늘 일어난 버그, 완벽히 기억해낼 수 있을까요?

개발을 함에 있어서 이슈는 여러개로 나타나기 마련입니다. Front-End 영역에서만 오류가 났으면 좋겠는데, Back-End 영역에서도 오류가 마구잡이로 생겨나기 마련입니다. 또한 그 오류는 내가 발견할 수 있지만, 타인이 발견할 수도 있습니다. 그런데 이걸 단순히 카톡방에서만 공유를 하거나, 구두로만 말을 전했다면.. 완벽히 기억해낼 수 있을까요?

 

2. Restful API 통신 규칙, 어떻게 설명해낼건가요?

또한 앱-웹에 통신에 있어 반드시 필요한 Restful API를 설계 같은 경우는, 백엔드 개발자가 Restful API를 설계를 하면 앱개발자에게 통신규칙을 설명을 해야 합니다. 하지만 통신규칙 같은경우는 Method, Params 등 여러가지 경우의 수를 생각해보면 정말 다양하게 있습니다. 이럴 때 어떻게 고지를 해줄까요??

 

 

위 두가지 케이스를 봤을 때 문서화는 반드시 필요한 작업입니다.

이번 글에서는 어떻게 문서화로서 내용을 정리를 했는지 설명해보고자 합니다.

 

 

• Github Issue : 문제가 발생되거나, 새로운 기능을 만들어야 할 때!

일단 첫 번째로, Github Issue에 대해 먼저 소개해보고자 합니다.

 

 

Github Issue 같은 경우는 Github Repository 내에 존재하는 기능 중 하나로서, 해당 저장소의 개발에 있어 이슈가 될 만한 사안이 있을 경우 해당 저장소 내에 등록을 할 수 있도록 도와주는 기능입니다.

 

캐치딜 프로젝트 같은 경우는 Front End 영역이랑 Back End 영역이랑 Repository가 나뉘어져 있습니다.

그렇다보니 만약 백엔드 개발자가 프론트엔드 개발자에게 뭔가 버그를 찾아내가지고 제보를 하거나, 새로운 기능에 대해 제안을 하고 싶다면 말로 하는 방법도 있긴 하지만, 이는 금방 까먹을게 뻔하니 메모를 하는게 획기적입니다.

 

그래가지고 저희같은 경우는 이렇게 Issue 등록을 통해 버그, 새로 개발해야할 것 들에 대해 메모를 남겨둡니다.

 

 

이렇게 이슈등록을 통해 하면 단순히 카카오톡으로 통해 얘기를 나누는 것 보다 더 기억에 남고, 더 체계적으로 정리가 됩니다.

 

 

• Restful API 규칙 설명 문서화

RESTFUL API같은 경우는 Method만 봐도 GET/POST/PUT/PATCH 방식이 있고, 또 다양한 Parameter 방식으로 서버에 Request 요청을 할 수 있습니다. 하지만 이러한 경우의 수가 다양한데.. 이를 어떻게 문서화를 해야 할까요?

 

Github Wiki

처음에는 저는 Notion 혹은 Github Wiki를 통해 Restful API 문서화를 할까 고민을 했습니다.

하지만 그 때 당시에는 좋은 아이디어이긴 했지만, 지금 되돌이켜보면 썩 좋은방법은 아니었던 것 같습니다.

 

일단 API 문서화 이야기에 앞서, Postman 개념을 간략하게 설명하고 이어나가보겠습니다.

 

Postman : Restful API 테스트 때 쓰이는 툴입니다.

Postman은 홈페이지에 파라미터와 함께 Request 신호를 쏘면 Response 응답을 확인을 할 수 있도록 도와주는 툴입니다. 보통 Restful API를 운용하는데에서 Request/Response 테스트용으로 많이 쓰는 것으로 알고 있습니다.

 

저 또한 Restful API 설계를 하면서 위 툴을 통해 요청/응답에 대해 많이 활용을 했습니다.

그런데 어느 날 이 툴을 쓰면서 재밌는 기능을 하나 알게 됩니다.

 

 

Postman 프로그렘에서 약간의 설정만 거쳐주면 웹페이지에 위와같이 Restful API에 대한 문서가 자동으로 셋팅이 되고, Request 응답이 무엇이냐에 따라(200, 400, 401 등) 다양한 샘플응답을 받아낼 수 있었습니다.

다양한 샘플응답, Request 요청에 있어 언어에 따라 어떻게 코드를 짜야하는지 알려주는 저 장점 덕분에 Github Wiki 혹은 Notion을 택하지 않은게 정말 큰 다행이었습니다.

 

Postman으로 API Document를 어떻게 만들어야 하는지는 아래 블로그 내용을 참고해주세요.

 부록  Postman으로 API Document 만들기

 

 

• 마무리

사람은 망각의 동물인 만큼 오늘/내일 개발해야 할 목록과, 그날그날 발견한 버그에 대해서는 단순히 카카오톡 만으로 공유해서는 안되고, 문서화를 통해 못박아놔야 합니다.

또한 혼자 개발한다 친다 해도, '오늘 내가 뭘 했고, 어떤 버그를 발견했는지' 에 대해서도 메모를 하는 습관이 정말 중요한 것 같습니다. 내일이 되면 그렇게 잘 기억했던게 다 까먹을 수 있기 때문입니다.

 

오늘도 이 블로그를 작성하는 백엔드 개발자는.. 글을 마치면 다음날 새로운 기능을 개발 준비를 하기위해 깃헙 이슈 메모를 봐야겠습니다..ㅠㅠ

 

 

 

• 캐치딜 개발 이야기 연결고리

1. 캐치딜 백엔드 개발이야기 : 좌충우돌 서버 설계 및 운영 이야기

2. 캐치딜 백엔드 개발이야기 : 문서화

3. 캐치딜 백엔드 개발이야기 : 디자이너와의 협업

4. 캐치딜 백엔드 개발이야기 : 크롤링

5. 캐치딜 백엔드 개발이야기 : Restful API 설계의 다양한 고민

6. 캐치딜 백엔드 개발이야기 : 나에게 맞는 합리적인 서버 비용을 찾아서..