개요
UMC에서 간단한 블로그 CRUD를 만들라는 미션이 있었고, API 명세서를 작성해야 하는 필요가 있었다.
그런데 이번에는 저번 넘블 인스타그램 챌린지를 하면서 적용하고 싶었던 GitBook 도구를 활용하고 싶었고, 해당 작업을 하면서 알게 된 정보를 작성하려고 한다.
GitBook 소개
GitBook은 개인, 팀이 문서화를 할 때 유용하게 사용할 수 있는 서비스이다. 많은 기능이 있지만, 일단은 API 명세서를 만들기까지의 과정을 보도록 하겠다.
API 문서화 작성 절차
가입
우선 Sign up with GitHub를 클릭하면 다음과 같은 화면이 나온다. 깃허브를 통해서 인증한다.
Organization 설정
GitBook을 사용할 때 이용할 organization 이름과 용도를 정할 수 있다. 아래에서는 UMC blog API로 설정했는데, 후에 보니 진짜 말 그대로 계속 사용될 이름을 뜻하는 것이었다. 그 점을 고려해서 작성하도록 하자. (그래서 이후에는 UMC로 변경하였다.)
메인 페이지
메인 페이지를 들어오면 아래와 같은 화면이 뜬다. 맨 왼쪽은 조직의 이름과 각 팀들이 보여지며, 가운데는 현재 만들어진 페이지들을, 맨 오른쪽은 현재 작업중인 페이지를 나타낸다.
새 페이지 만들기 + 그룹
커서가 가리키는 + 버튼을 클릭하면 아래와 같은 창이 나온다. 페이지를 만들거나, 그룹을 만들 수도 있다. 그룹은 예시로 User에 대한 API들을 작성하는 데 사용될 수 있다.
작업 종류
페이지의 작업들은 다음과 같은 것들이 있다. 수식을 작성할 수도 있고, 일반 텍스트를 작성할 수 있는 등 기능이 많이 있다.
여기서 우리가 필요한 것은 주로 일반 텍스트와 API Method이다.
API Method
API Method를 새로 생성하면 다음과 같은 구조로 되어있다.
Parameters
아래는 Parameters를 추가할 때 등장하는 화면이다. 필요한 것에 따라 추가하면 된다.
예시로 Parameters를 새로 추가하면 아래와 같은 식으로 생성되는데, placeholder 되어 있더라도 진짜 아무 텍스트도 작성하지 않으면 비워지게 되니 주의하자. (ex: String 부분을 비워두면 실제 화면에서도 비워진다.)
Response
Response로는 다양한 것들을 선택할 수 있다. 여기에 없더라도 상태코드를 입력하면 있을 것이다.
하나 생성하면 다음과 같이 세부 설명을 작성할수도 있다. Paragraph를 이용해 설명을 할 수도 있고, Code Block을 선택해 알맞은 JSON 예시 등을 넣을 수도 있다.
아쉬운 점은 한글 입력을 할 때 살짝씩 밀리는 게 있다. 다른 곳에서 작성한 다음 붙여넣기를 하는 게 좋아보인다.
작성한 예시
작성해 본 예시는 다음과 같다. (실제 주소에서 /users는 뜨지 않는다. http://localhost:8080/post 까지만 나온다.)
배포
장점 중 하나라고 느껴지는 것은 쉬운 배포이다. 스웨거는 내가 직접 배포하는 과정이 있어야 했던 것으로 알고 있는데, 여기에서는 매우 쉽게 웹사이트로 만들어준다. 오른쪽 상단의 버튼을 클릭하면 다음과 같이 공유가 가능하다.
배포 결과
실제 웹사이트를 확인해보면 다음과 같이 나온다. 내 API 문서는 이곳에서 확인 가능하다.
참고 & 참고하기 좋은 곳
지금은 API 문서만을 작성하느라 GitBook의 다른 기능들을 작성하지는 못했다. 추가적인 기능들을 더 확인하고 싶다면 아래 사이트를 참고하면 좋을 듯 하다.
부족하거나 설명을 보완해야 할 것이 있다면 댓글 부탁드립니다 😃
