[팀프로젝트] API 문서 작성이 협업 시 필수인 이유

기능 구현을 위해 API 문서를 작성했다.

API 문서 작성이 왜 필요할까

이전에 개인프로젝트를 진행하면서 API 스펙을 적고 작업을 했었다. 이때 API 문서를 작성한 이유는 그저 기록으로 남겨두기 위해서였다. 그러다보니 작업 후반부터는 API 스펙을 정하는것의 필요성을 느끼지못해서 작업 먼저 끝내고 몰아서 작성하기도 했다.

하지만 이번에 팀프로젝트를 해보니 API 문서를 미리 작성하는게 왜 필요한지 알 수 있었다.

• 표준화를 통해 팀 간에 일관성 있는 개발과 커뮤니케이션이 이루어질 수 있다.
• 일관된 API 스펙을 통해 데이터와 서비스의 교환이 원활하게 이루어질 수 있다.

여러가지 이유가 있겠지만 내가 느낀 것은 이 2가지이다.

팀 단위로 협업을 하니 프론트엔드, 백엔드 둘 다 혼자서 구현해야할때와 다르게 프론트엔드에서 어떻게 데이터를 받기 원하는지를 미리 정해두고 작업을 해야했다. 그래야 효율적으로 작업할 수 있고 이는 코드의 질을 상승시키는 요인이기 때문이다.

현재 작성한 API 문서에서 개선할 부분

1. 더 정확한 정보

일단은 간단하게 노션에 각각의 기능에 대한 API 스펙을 적었다.

하지만 이것도 기능 구현을 하다보니 더 정확히 적어야 한다는걸 깨달을 수 있었다.

예를들어 동일한 API 호출에서 발생할 수 있는 에러에 대한 설명이나 코드 같은것도 필요했다.

2. API 작성 툴 선택

이전 개인 프로젝트에서는 노션에 먼저 작성하고, 모든 기능을 구현한 후 apiDoc을 이용해 문서를 다시 작성했었다.

이번에도 다시 프로젝트를 하면서 '일단 간편하게 노션에 적고 나중에 옮기자'라고 생각하며 작업을 했다. 하지만 다시 생각해보면 이런식으로 작업하는건 할 일만 두배로 늘어나고, 노션에 적는게 API 툴을 이용하는 것보다 간편하지도 않다.

따라서 API 툴도 먼저 정하고 한번만 작성하는게 좋을것 같다.