백엔드가 이정도는 해줘야 함 - 6. API 스펙 설계와 문서화 방식 결정 - (2)

API 스펙 설계가 끝났으니 이제 프론트엔드 팀에게 전해줄 문서를 작성해야 한다. 이거야 뭐 대충 마크다운같은 걸로 열심히 시간 쏟아서 정리해도 되는 부분이지만, 더 나은 방법이 없을지부터 고민해 보자. 이번 챕터에서는 API 문서화 방식을 결정한다.

의사결정

API 문서화 방식

난 처음에 엑셀로 API를 문서화했다. 메소드 URI, 요청 파라미터, 응답 status code별 설명, 응답 body 등등을 컬럼으로 두고 내용을 채웠었다.

이게 어떤 문제가 있냐면,

• 변경을 추적하기 어렵다.

• 변경이 생길 때마다 프론트엔드에게 새로운 파일을 전달해줘야 한다. 대안으로 Google Sheets같은 중앙화된 문서화 도구를 쓰는 방법이 있다.

• 엑셀과 같은 모던한 문서화 도구들은 중복을 추상화하기 어렵다. 예를 들어, '게시글 작성'과 '댓글 작성' API의 response body 포맷이 동일하다고 치면, API 문서화에 특화된 도구들은 이걸 따로 분리해서 참조할 수 있게 만들어져 있다. 중복 제거는 통일성 있는 확장을 위해 중요한데, 이걸 포기하는 셈이다.

• 가독성이 나쁘다. 비슷한 endpoint끼리 묶어서 카테고리화 시키고, 설명에 테이블이나 리스트와 같은 HTML 기반의 컨텐츠를 추가하는 등의 일이 힘들다(적어도 엑셀 많이 안 다뤄본 나로서는).

그냥 API 문서화 도구의 결과물을 사진으로 만나보자.

HTTP API의 문서화 방식을 표준화시키기 위해, yaml 파일로 작성하는 형태의 OpenAPI라는 스펙이 존재하며 거의 모든 API 문서화 도구들은 이런 OpenAPI 스펙에 대응되어 있다. 따라서, OpenAPI 스펙에 따라 작성한 API 문서를 시각화해줄 도구를 선택해야 한다. 간소화된 문법으로 작성한 문서를 OpenAPI 포맷으로 convert해주는 도구라면 더 좋고. 또는 OpenAPI 신경 안쓰고 GUI 방식으로 문서를 작성하는 자체적인 문서화 서비스일 수도 있다.

배경과 요구사항

• 변경을 추적하기 쉬워야(버전 관리가 가능해야) 한다. Git으로 관리할 수 있는 것이라면 더 좋다.

• 문서를 작성하는 일이 고통스럽지 않아야 한다. raw한 OpenAPI 3.0 spec은 유지보수하기 정말 쉽지 않다.

• UI가 예뻐야 한다.

• Private로 관리할 수 있어야 한다.

선택지

• Excel

• SwaggerHub(Example)

• 소스코드에 문서 임베딩

• ReDoc을 직접 관리

• ReDoc을 GitHub Pages(github.io)에서 관리(Example)

• Slate를 직접 관리

• Slate를 GitHub Pages(github.io)에서 관리(Example)

• GitBook

의사결정

GitBook을 사용하겠다. 그 이유는,

• Excel을 쓰는 방식은 너무 구리다.(위에서 말했던 것처럼)

• SwaggerHub는 OpenAPI 스펙 그대로 문서를 정의해야 한다. 따라서 모든 API를 한 페이지(파일)에서 관리해야 하는데, API 한 대여섯개만 넣어도 가볍게 1000줄이 넘어가서 관리가 힘들다.

• 소스코드에 임베딩하는 방식은, 라이브러리 단에서 HTML+CSS 리소스 + 소스코드에서 추출한 문서 정보를 가지고 있다가 /docs 같은 uri에서 문서를 웹으로 서빙하는 형태다. 유명한 것으로는 Flask 기반의 flasgger가 있다. 소스코드에 문서가 포함되어 있으니, 리뷰 과정에서 API 스펙이 변경되었을 때 이를 문서에도 반영했는지 볼 수 있어서 좋고 대부분 API 각각에 문서가 주입되는 형태라서 가독성도 괜찮다. 그러나 API 문서의 수정이 필요할 때마다 어플리케이션 전체를 다시 빌드하고 배포해야 해서 리스크가 크다. 따로 분리하는 것이 좋겠다고 생각했다.

• ReDoc과 Slate는 OpenAPI 스펙에 맞춰진 문서를 조금 더 간소화된 문법으로 작성할 수 있어서 좋은데, 직접 관리하는 경우 조금 귀찮다. Amazon S3 website같이 스토리지 서비스에서 정적 웹사이트를 호스팅하는 형태로 관리하게 될텐데, 변경을 자동으로 배포하기 위해 배포 자동화를 설정해야 할테고, API가 외부로 공개되어야 한다면 status check도 붙어야 하고, 상황에 따라 ReDoc이나 Slate에서 제공하는 React App을 커스텀하기도 해야 한다. 관리 포인트가 늘어나기 때문에 보류.

• 관리 포인트가 감당 가능하다 하더라도, ReDoc과 Slate가 간소화한 문법을 쓰는 것이 사실 경험 상 문서를 작성하는 데에 생산성이 그렇게 비교될 정도로 좋지는 않았고 썩 즐겁지도 않았다.

• 관리 포인트를 줄인답시고 ReDoc과 Slate를 GitHub Pages에 올리는 경우, 문서를 private로 관리할 수 없다.

• GitBook은 문서 작성에 대한 스트레스가 비교적 적다. GUI로 작성하기 때문. 내부적으로 OpenAPI 스펙으로 관리하고 있지는 않고 그냥 자체적인 API 문서화 툴이다. 과거에도 여기저기서 GUI 기반의 API 문서화 플랫폼을 개발하고자 하는 시도가 많았지만 조잡했어서 안 썼는데, 최근에 들어가 본 GitBook은 괜찮았던 것 같다.

OpenAPI에는 $ref라는 문법으로 중복을 관리할 수 있어서 좋은데, GitBook은 그렇지 않다. 하지만 편히 문서를 작성할 수 있으니 트레이드오프 한다고 생각하자.

작업

API 문서화

GitBook에 로그인하고, workspace를 만들어서 API를 문서화하자.

일러두기

API 문서는 한 번 쓰고 끝?

협업을 하게 될 팀원들과 협의하는 과정이 있어야 한다. 나는 이 과정이 '무조건' 있어야 하며, API 문서를 작성하는 것에 있어선 항상 '떠벌리기 좋아하는 사람'이 되어야 한다고 생각한다. 백엔드 조직 단에서 API 문서화가 마무리되면, 타 팀원들에게 공유하고 피드백을 받자. 가능하다면 링크만 뚝딱 전달하지 말고, 아예 만나서 같이 리뷰하는 시간이 있으면 더욱 좋다.

지금까지

• 버전 관리 시스템으로 Git을 사용하기 시작했다.
• Git 웹호스팅 서비스로 GitHub를 사용하기 시작했다.
• GitHub Issues와 Projects로 이슈 트래킹을 시작했다.
• 개발 프로세스와 브랜칭 모델을 정립했다.
• HTTP API 아키텍처 기반으로 API 스펙을 디자인하기로 했다.
• JSON을 직렬화 포맷으로 결정했다.
• Authorization 헤더로 인증 정보를 명시하기로 했다.
• 인증 스키마에 JWT 기반의 Bearer를 사용하기로 했다.
• API 스펙을 정의했다.
• GitBook으로 API를 문서화했다.