지난번에 Swagger를 통해 OpenAPI에 대한 specification을 작성하고, Swagger-UI를 통해 브라우저상에 띄우는 것을 해보았는데 이번엔 GitBook을 통해 Api 명세서를 작성해보자
왜 사용했는지?
사실 Swagger도 굉장히 편리했다. 특히, Nest에서 모듈로 제공하기 때문에 간편하게 코드로 작성할 수 있다는 장점이 있었지만...
규모가 커졌을 때 명세서를 작성하기 위한 코드량이 너무 길어질 것 같다는 점, GitBook을 보기 전까진 잘 못느꼈으나 Swagger-UI에 비해 UI가 더 보기 쉽고 사용하기 편할 것 같다는 점 때문에 기본적인 기능들만 사용을 해보았다.
GitBook이란?
그래서 GitBook이라 하면 팀 내부에서의 기술 자료 및 API까지 모든 것을 문서화 할 수 있는 최신 문서화 플랫폼이다.
GitBook은 md, html, docs와 같은 파일을 가져올 수 있고, 노션이나 컨플루언스에서 작성한 것들도 import시킬 수 있다고 한다.
Github 저장소에도 커밋해서 올릴 수 있지만 나는 내가 작성한 Api에 프론트엔드분을 초대해서 공유하였다.
그럼 시작!
페이지
왼쪽에 보면 하나의 페이지(API Reference)에 여러가지 목차(User/Auth, Video)를 생성할 수 있고, 페이지를 누르면 목차 별 설정한 설명과 해당 목차로 이동할 수 있게 해주는데 굉장히 편리했다.
API Method 작성
내용을 작성하는 것도 편리했는데 노션처럼 사용 가능했으며, 작성한 내용 밑에 새로운 것을 추가하고 싶으면 동그란X표시 된 부분에 마우스를 올려대면 작성할 수 있는 것들이 많이 나온다.
그 중 빨간색 밑줄 친 API Method를 눌러보면 바로 밑에 템플릿이 기본으로 제공이 된다.
그럼 이렇게 쉽게 Request Parameter들이나 상태코드 별 Response를 작성할 수 있고 Response에는 코드 블럭처럼 다른 언어들을 선택해서 작성할 수 있다.
그리고 수정사항 같은 경우 API Method를 추가할 때 고르는 항목에서 Info를 선택하면 Warning, Error, Info와 함께 공지 내용에 따른 정보를 작성할 수 있다.
팀원 초대
만약에 팀원들과 작성한 내용을 공유해야 한다면 오른쪽 상단에 invite를 클릭해보자
Email을 입력하거나 하단의 link를 보내 초대할 수 있다.
그리고 기본적인 접근 권한이나 초대된 멤버 별 활동 권한을 줄 수 있으므로 작성하는 사람이 혼자면 나를 제외한 팀원들은 읽을 수만 있게 권한을 주는 것도 괜찮은 것 같다.
사용후기...
사실 정말 기본적인 기능들만 사용해 보았기 때문에 엄청 어려운 것도 없었고, Swagger보다 훨씬 마음에 들었다.
나중에 어떤 도구를 사용할지는 모르겠지만 내가 고를 수 있으면 GitBook을 Github와 함께 연동해서 사용하면서 관리해보고 싶고 아니면 사용하는 도구를 더 공부를 해야겠다.
