API Workbench 시작하기

API Documentation tool로 Swagger를 쓰려고 하였으나 node 서버가 아닌 swift로 서버를 만드는 것과 설정상의 어려움으로 다른 tool을 찾게 되었습니다. 

API Workbench는 Atom에서 Package로 추가하여 사용할 수 있고 raml2html으로 html 파일로 뽑아낼 수 있어 쉽고 간단할 것 같습니다.

먼저 Atom을 설치합니다. 그리고 apm 으로 api-workbench를 설치합니다.

$ apm install api-workbench
Installing api-workbench to /Users/tongchunkim/.atom/packages ✓

Atom을 다시 실행시키면 api-workbench의 dependencies를 설치하라고 뜹니다. 설치해 줍니다.

설치하다 보면 dependencies의 dependencies로 여러개를 설치하게 됩니다.

dependencies가 모두 설치되었다면 Package에서 API Workbench > Create RAML Project를 선택해 시작합니다.

Creat RAML Project를 선택하면 기본 설정화면이 나옵니다.

프로젝트 이름과 URL를 입력하고 Create을 클릭합니다.

Atom에 설정한 RAML Project의 기본 화면이 보입니다.

이제 Documentation을 활용해 문서를 작성 합니다.

[http://apiworkbench.com/docs]

작성 방법에 대해서는 다음에 post 하겠습니다.

이제 raml을 html으로 변환해 봅시다.

npm을 이용해 raml2html을 설치합니다. raml2html은 기본 theme이 있으며 여러 종류의 theme이 있습니다. raml2html-markdown-theme을 설치하고 적용해 봅시다.

$ npm i -g raml2html
$ npm i -g raml2html-markdown-theme

설치가 되었다면 api.raml 위치에서 아래 명령으로 html로 변환해 줍니다.

$ raml2html example.raml > example.html

raml2html-markdown-theme을 적용하려면 아래와 같이 변환합니다.

raml2html --theme raml2html-markdown-theme example.raml > example.html

몇개 안되는것 같지만 다른 theme을 적용할수 있습니다.

https://www.npmjs.com/browse/keyword/raml2html-theme

Workbench 기본 사용 설명은 여기까지 입니다.