Slate, Swagger 2, ReDoc의 대안으로 훌륭한 API 문서 제작 툴

Slate란?

  • SlateHTML 형태의 API 문서를 만들어주는 도구이다. 정확히는 Ruby 기반의 HTML 실시간 렌더링, 빌드 기능을 가진 애플리케이션이다. Slate의 강점은 낮은 학습곡선, 자유도와 생산성이다. 흔히 API 툴링시 많이 도입하는 Swagger 2, ReDoc 조합이 여의치 않을 경우 매력적인 대안이 될 수 있다.

  • Slate 다운로드 후 하위 /source 디렉토리의 Markdown 문서들을 기반으로 API 문서를 작성하면 Slate가 미려한 UI의 반응형 웹으로 변환해준다.

  • 실시간으로 마크다운 문서를 확인할 수 있으며 또한 배포 목적의 HTML 빌드 기능도 제공한다.

  • Slate는 아주 간단한 Markdown 문법 만을 제공하기에 자유도가 상당히 높다. 문법 중간 중간 HTMLCSS를 허용한다. 예를 들어 BootstrapCSS를 임포트하면 그대로 HTML에서 사용할 수 있다.

Slate 설치

  • Slate는 어떤 운영체제에서도 개발이 가능하다. Ruby, Bundler, Node.js만 사전 설치되어 있으면 된다. CentOS 6을 예로 들어 개발환경을 구성해보자.
# Ruby, Bundler 설치
$ cd ~
$ wget https://github.com/feedforce/ruby-rpm/releases/download/2.3.4/ruby-2.3.4-1.el6.x86_64.rpm
$ sudo yum install -y ruby-2.3.4-1.el6.x86_64.rpm
$ sudo gem install bundler

# Node.js 설치
$ curl --silent --location https://rpm.nodesource.com/setup_6.x | sudo bash -
$ sudo yum install -y nodejs gcc-c++ make

# Slate 설치
$ git clone https://github.com/lord/slate.git
$ cd slate

# Bundle 실행(소스 코드를 내려 받은 최초 1번만 실행)
$ bundle install

Slate 개발 서버 구동

  • Slate 설치가 완료되었으면 /source/index.html.md/includes/*.html.md를 작성하여 API 문서를 작성하면 된다. 아래와 같이 Middleman을 구동하여 작성된 파일의 실시간 브라우저 확인이 가능하다. (기본값은 HTTP 4577번 포트로 실행된다.)
# Slate 서버 실행
$ bundle exec middleman --watcher-force-polling

Slate 빌드

  • 작성이 완료된 API 문서를 빌드하려면 아래와 같이 실행한다. /build 디렉토리에 진입점이 되는 index.html과 기타 파일들이 생성된다. 빌드된 파일들을 클라이언트에게 전달하거나 웹사이트에 배포하면 된다.
# Slate 빌드 실행
# bundle exec middleman build --clean
저작자 표시 비영리 동일 조건 변경 허락
신고