Slate란 무엇인가 + 사용법
in Open Source on Open Source
Slate란
Slate는 HTML 형태의 API 문서를 만들어주는 도구이다.
공식 문서인 깃허브 페이지에서는 다음과 같이 Slate를 설명하고 있다.
Slate는 아름답고 지능적이며 반응이 빠른 API 문서를 만드는 데 도움이 된다.
실제 예제 사이트는 아래를 참조하시라.
https://slatedocs.github.io/slate/#introduction
UI가 너무 예쁘다. 합격!/
Slate 사용법
거두절미하고 당장 Slate를 사용해보자.
Slate를 사용하기 위해서는 먼저 slate 프로젝트를 포크를 따야한다.
우측 상단의 Use This Template 버튼을 눌러 내 레포지토리에 포크하자.
git clone https://github.com/YOURUSERNAME/slate.git
그리고 나서 git clone 명령어로 포크뜬 레포를 로컬에 저장해주자.
그리고 나서 다음 스텝을 통해 루비를 먼저 설치해주자. 환경은 Mac OS를 기준으로 하였다.
Slate를 구동하기 위해서는 루비가 필요하다.
루비 설치에 관해서는 아래의 블로그를 참조할 것!
https://jojoldu.tistory.com/288
cd slate
bundle install
bundle exec middleman server
exec이 완료되면 http://localhost:4567/ 로 접속해보자.
단 세 줄만에 Slate를 구동시켰다.
매우 간단하고 직관적이다!
직접 써본 후기
상당히 UI가 깔끔하다.
빌드하는 것도 엄청 쉽고 직관적이다.
우선 편집해야하는 파일이 index.html.md 파일 하나라는 점도 매력적이다.
문서도 마크다운 기반으로 작성할 수 있고 예제도 잘 되어있는 편이라 보고 따라하면 금방 API 문서 정도는 뚝딱 만들 수 있을 것 같다.
약간의 TMI
이 Slate라는 것을 알게된 계기는 파트장인 쉘던이 slate를 공유해주셔서 처음으로 알게 되었다.
팀의 서비스가 계정 체계이다보니 우리의 서비스를 사용하는 다른 여러 팀들과 협업할 일이 많았고,
그러다 보니 자연스럽게 가이드 문서나 API 문서의 필요성을 점점 느끼게 되었다.
기존에는 Swagger를 사용하고 있었는데, Swagger는 아무래도 코드에 애노테이션이 붙다 보니 장황한 설명을 쓰기가 조금 아쉬웠다.
그래서 나는 Rest Docs를 추천했지만, 조금 생각해보니 Rest Docs 자체가 적용하기가 꽤 어려운 편이고 기존 서비스의 테스트 코드가 이미 프레임워크 처럼 구조화가 잘 되어있다 보니 선뜻 Rest Docs를 도입하는게 쉽지만은 않을 것 같아 보였다.
그리고 어차피 모든 API에 대한 문서가 필요한 것도 아니고, 개인적으론 Rest Docs의 UI 자체도 예쁜 편은 아니라고 생각했다.
그러다 쉘든이 Slate의 깃허브 페이지를 공유주셨고, 놀랍게도 3만개에 달하는 스타가 있는 엄청난 프로젝트라는 것에 우리는 감탄했다. (스프링 프레임워크가 4만개인 것을 감안하면 엄청나다)
그래서 쉘든이 한번 리서치를 해볼 것을 말씀하셨고 나 또한 흥미가 생겨서 이번에 한번 구동시켜보았는데 설치도 간단하고 편집도 쉬워서 배포하는 것에도 크게 문제가 없을 것 같아 보인다.
Swagger와 같이 쓰되, 자세한 설명이 필요한 API라면 Slate를 도입해보는 것도 좋을 것 같다.
Reference
https://jojoldu.tistory.com/288
https://github.com/slatedocs/slate/wiki/Using-Slate-Natively