API 문서화 도구 Slate

 

 

회사에서 프로젝트 개발 관련 다큐멘트를 작성 업무를 배정 받았는데..

Swagger를 쓰기에는 너무 평범하기도 대중적이기도 하고..

깃북을 쓰자니 이쁘게 뽑히긴 하지만 유료라서 뼛속까지 짠돌이인 나한텐 맞지 않았다. 

 

그래서 오픈소스 API 문서화 도구가 없나 찾아봤는데 역시나 없을리가?

Slate라는 툴을 발견했다.

 

디자인이 이쁘기도 하고.. 마크다운문법으로 index.html 파일 하나만 수정하면 되기에 너무 편하다는 것이 장점

물론 설치과정이 까다롭다면 까다롭다고 말할 수 있을터..

하지만 개발자인 우리에게 뭐 하나 쉬운것이 있던가?ㅋㅋ

 

아무튼 Slate를 설치하고자 하는 사람에게 이 문서가 도움이 되길 바라며 글을 써본다.

작성자는 Slate를 윈도우 랩탑에 설치했다.

 

자 그럼 따라해보자 !

 

우리는 Slate를 WSL을 사용해 리눅스에서 돌릴것이다.

아래 링크를 통해 WSL을 설치하자. 

https://docs.microsoft.com/ko-kr/windows/wsl/install-win10

Windows 10에 WSL 설치

 

WSL을 설치했다면 윈도우키를 눌러 Microsoft Store를 입력후 들어가자.

작성자의 컴퓨터에는 Ubuntu 20.04 LTS버전을 설치했다.

마음에 드는 리눅스 버전을 검색해서 설치하자. (가급적 최신버전 LTS) 

 

설치 했다면 본격적으로 설치하기위해 리눅스 실행 !

패스워드 등 설정해주시고..

 

 

cd ~

sudo apt-get update

sudo apt-get install nodejs

sudo apt-get install zlib1g-dev buid-essential ruby-full

sudo gem install bundler

위 커맨드로 Linux에 Slate를 돌리기 위한 Ruby와 bundler를 설치하자!

nodejs도 설치해줘야한다!

 

 

 

git clone https://github.com/lord/slate.git

cd slate

bundle install

그런 다음 위 커맨드로 slate 레포지토리를 클론하고서

cd slate 커맨드로 디렉토리 내부에 진입.

그리고 Slate를 실행해줄 bundle을 설치하자!

 

 

 

# Slate 빌드 커맨드
bundle exec middleman build --clean

# Slate 서버 실행 커맨드
bundle exec middleman --watcher-force-polling

위 커맨드는 Slate 문서 빌드, 서버 실행 커맨드다. 

Slate는 호스티드 툴이기 때문에 서버를 실행하지 않으면 볼 수 없다.

 

 

자 이제 세팅은 완료됐고,

index.html.md 파일을 수정해서 문서를 작성하면 된다.

문서 수정 후, 위 빌드 커맨드를 실행 후 서버를 실행해줘야함을 잊지말자 !

 

참 그리고 index.html.md 위치를 못찾는 사람들이 많던데

WSL 디렉토리는 파일 탐색기에 다음을 입력해 진입할 수 있다.

\\wsl$

 

cd ~ 커맨드를 사용해 사용자 디렉토리에 설치했다면

index.html.md 파일의 경로는 다음과 같을것이다.

\\wsl$\사용자리눅스버전\home\사용자계정명\slate\source

 

 

자 그럼 이제 서류 쓰러 갑시다.