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

Slate란?

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


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


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


• Slate는 아주 간단한 Markdown 문법 만을 제공하기에 자유도가 상당히 높다. 문법 중간 중간 HTML과 CSS를 허용한다. 예를 들어 Bootstrap의 CSS를 임포트하면 그대로 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

발견된 문제점

• 좌측 네비게이션 메뉴의 검색 기능(문서 상에서 search: true로 활성화)은 한글 문자열에 대해서 작동하지 않는다. 한글 문서라면 사용하지 않는 편이 낫다.


• v2.0의 경우 좌측 네비게이션 메뉴의 각 항목(문서 상에서 # 또는 ##으로 정의된 부분)이 한글과 같은 UTF-8 문자열로 시작할 경우 메뉴 기능이 정상적으로 작동하지 않는다. 다운그레이드하여 v1.5 버전을 사용하거나 앞에 숫자 또는 _ 문자열을 접두어로 붙이면 해결된다.