grep

Engineering

JBake로 API문서 관리하기

NHN

2017년 12월 21일

원문에서 보기 ↗

1. 프로젝트 배경 및 목적

2. 용어설명

설명하기 전에 앞으로 자주 등장할 용어들에 대해서 간략하게 소개해드리도록 하겠습니다.

3. Static Gen과 CMS의 관계

사실, JBake는 CMS가 아닌 Static Gen입니다. Static Gen은 CMS가 가질 수 있는 여러 기능 중 하나의 기능을 하는 Tool이라고 볼 수 있습니다. Static Gen은 Markdown 형태의 원본 문서로부터 HTML 형태의 정적인 사이트를 생성하는 기능을 합니다.[참고]

Staitc Gen은 다양한 형태의 원본 소스파일을 취급합니다. 
(ex. AsciiDoc, Markdown, XML, JSON, YAML, old HTML...)

1.png

CMSStatic Site Generator
- 효율적으로 사이트 문서를 관리할 수 있게 도와주는 시스템 - 문서관리를 위해 다양한 기능을 하는 여러 tool들을 호스팅 - CMS마다 각기 다른 tool들을 갖고 있음 ※ 대표적으로 Read the Docs가 여기에 속함- 소스코드로부터 HTML형태의 문서를 생성해내는 tool - CMS가 호스팅하는 여러 tool 중 하나 ※ 대표적으로 Jbake가 여기에 속함

[표 1] CMS와 Static Site Generator의 차이

■ Research & Development

※ 진행전략

이 프로젝트는 API 문서관리를 할 수 있는 Java 기반의 CMS를 찾는 것입니다. 하지만 실제로 이것이 API 문서관리에 적용될 수 있을지 없을지는 적용해 보기 전까지 알 수 없습니다. 따라서 저희는 '프로토타이핑 개발 방법론' 을 사용하였습니다.

Step 1) API 문서관리 시스템이 가져야 할 조건들을 최대한 만족하는 CMS를 선정한 뒤 이것을 이용해 프로토타입 개발(성능 / 효율 / 보안 고려 X)
Step 2) 개발한 프로토타입을 이용하여 TOAST Cloud API 문서 사이트에 적용해 봄 만약 제대로 된 문서관리를 하지 못한다면 다시 Step 1 과정으로 돌아감
Step 3) Step 2에서 통과했다면 프로토타입 성능 보완 개선

1. CMS 리서칭

CMS는 여러 종류가 있으며 각각의 CMS들이 가지는 기능은 다양합니다. 모든 기능을 다 만족할 필요는 없습니다. 자신이 운영하고자 하는 문서사이트를 효율적으로 관리할 수 있게끔 해주는 기능만 갖추고 있으면 됩니다.

1-1. 오픈소스 Tool 선정

저희가 일차적으로 해야 할 일은 API 문서관리를 위해 필요한 조건을 최대한 만족하는 오픈소스 Tool을 찾는 것이었습니다. 만약 찾아낸 오픈소스가 만족하지 못하는 사항들이 있다면 이 부분에 대해서는 저희가 별도로 개발을 해야 합니다. 이러한 이유로 이번 리서치에서의 핵심은 API 문서관리를 위한 기능을 최대한 만족하는 CMS를 찾아냄으로써 개발비용을 최소화하는 것입니다.API 문서관리 CMS로 선정되기 위한 최소 요구사항은 아래와 같습니다.

① 최소요구사항

다음은 라이선스 조건을 만족했던 대표적인 Java 기반의 Tool을 비교한 표입니다.

요구사항JBakeSwaggerHippo
GitHub연동O△(유료)X(GitHub연동 지원안함)
.md(Markdown) -> .html(HTML)O△(JSON/YAML 지원)X(XML 지원)
버전관리XO△(수정 이력에 대한 관리)
BootstrapO△O
EditorXOO

[표 2] Java기반 CMS 비교 Swagger와 Hippo는 편리한 에디터 기능을 제공하고 있으며 현재 많은 사람이 사용 중인 대표적인 CMS입니다. 이 두 개의 CMS는 Markdown파일을 취급하지 않으며 디렉터리 구조를 반영한 결과물 생성이 불가능합니다. 또한, Swagger는 정적 사이트 생성보다는 REST API 문서화에 특화되었기 때문에 Bootstrap 지원이 빈약합니다.JBake는 단지 Markdown(.md)파일을 사이트 형태의(.html) 문서 파일로 변환해주는 'Static Gen'입니다. 저희는 이 셋 중에서 JBake를 선택하였는데, CMS라기보다는 부속품 역할만을 하는 Jbake를 선정한 이유는 다음과 같습니다.

② JBake 선정 이유

원하는 형태의 결과물(HTML 파일)만 생성해 준다면 GitHub와 연동하여 versioning하는 부분은 다른 오픈소스 tool을 이용하여 어렵지 않게 구현할 수 있을 거라 판단했습니다. 따라서 이러한 이유로 JBake를 TOAST Cloud API 문서관리에 적용해 보기로 결정하였습니다.

1-2. JBake 소개

① JBake란?**

② JBake 폴더 구조

아래 사진은 JBake의 root폴더에서의 모습입니다. 2.png 각 폴더 및 파일의 역할은 다음과 같습니다.

2. 프로토타입 설계 및 개발

2-1. Issue 사항

① GitHub 연동 및 문서 버전관리 불가능

앞에서 말씀드렸듯이 JBake의 역할은 단순히 Markdown 파일로 부터 HTML 파일을 생성하는 것이기 때문에 GitHub관 연동하여 브랜치별로 버전 관리를 하기 위해서는 이러한 기능을 해줄 수 있는 또 다른 Tool을 이용하여야 합니다.

****② 메뉴바 생성 및 동작 오류

JBake로 TOAST Cloud API 문서 사이트와 같이 만들기 위해서는내비게이션 사이드 메뉴바 생성 및 선택한 메뉴를 active 하기 위한 별도의 조치를 취해야 합니다.

2-2. Issue 해결

① 첫번째 Issue

GitHub 연동 및 문서 버전관리 불가능 -> 해결: "Jenkins와 결합" 다음은 Jenkins를 이용한 GitHub Repository와의 연동 그림입니다. ◎ GitHub와 연동한 문서 버전관리 3.png [각 단계 설명]

1. Markdown 형태의 문서를 배포용 real 버전과, 개발용 dev 버전 별로 branch를 달리하여 따로 관리
2. 문서담당자가 수정된 문서를 GitHub Repository에 commit
3. dev 버전의 문서를 real 버전에 반영하고 싶다면 merge
4. 특정 버전의 문서 삭제 원할 시 delete
5. 수정한 문서를 공유 저장소에 반영하고 싶을 시 git remote repository에 push
6. Webhook을 통해 이벤트 감지한 jenkins server는 repository에 있는 파일을 pull
7. build를 통해 문서사이트 생성 (Markdown -> HTML)
8. 운영 서버로 배포

그러나 위 과정을 통해 생성된 결과물은 빌드되었던 GitHub branch에 따라 별도로 생성해주지 않고 하나의 디렉터리에 계속해서 덮어씌우게 됩니다. 저희는 생성된 문서사이트까지도 버전별로 생성 되게끔 하고 싶었습니다. 따라서 저희는 한가지 아이디어를 내었는데 그 내용은 다음과 같습니다.

build.gradle에서 빌드의 결과물을 위치를 지정할 수 있습니다. 이것을 이용해서 문서 version 별로 build.gradle의 내용을 달리해 줍니다.

위 내용을 간단하게 다시 한번 설명하자면 각 branch에 위치한 build.gradle파일에서 결과물 생성하는 코드 부분을 각기 다르게 설정함으로써 결과물 생성이 branch 별로 다른 위치에 생성되게끔 하는 것입니다. 이것은 마치 github Repository에 변경된 마크다운 문서를 해당하는 버전의 branch에 push 하기만 하여도 자동으로 HTML 문서 사이트를 버전별로 따로 관리해 주는 것과 같은 효과를 줍니다.결과 생성물까지 버전별로 관리하기 위해 수정했던 사항들은 다음과 같습니다. ◎ Git과 연동한 문서버전관리 + 생성된 HTML문서까지 버전관리 4.png [build.gradle에서 결과물 생성 관련 코드] 5.png

[빌드 후 버전별로 결과물 생성된 모습] 6.png

② 두 번째 Issue

: 메뉴바 생성 및 동작 오류 -> 해결: "Javascript를 이용한 메뉴바 동작" 기존의 문서 사이트의 메뉴바 기능 동작을 위해서 Jbake에서 별도의 작업이 필요했습니다. 우선, 실제 운영 중인 TOAST Cloud API 문서 사이트에서의 메뉴바 동작 기능은 다음과 같습니다.7.png ◎ Toast Cloud API 문서 사이트의 메뉴바 기능

이러한 메뉴바들이 제대로 생성되고 동작하도록 하기 위해서는 다음과 사항들을 이해하고 있어야 합니다.

◎ 메뉴바 issue 해결을 위해 필요한 사전 지식

※ 페이지 템플릿 8.png 위 모습은 Jbake가 기본적으로 제공하는 페이지 템플릿 파일의 모습입니다. 각 위치에 미리 정의해 놓은 템플릿 파일을 include 하여 마치 조립 블록을 맞추듯이 페이지의 골격을 정의한 것을 볼 수 있습니다. 페이지마다 다른 본문의 내용은 ${content.body}변수를 통해 참조하여 본문 위치에 내용을 채워 넣습니다.

8-1.png - 위 코드는 content 폴더 속 Markdown 파일의 가장 윗부분의 모습입니다. 이 부분을 '메타 데이터'라고 부릅니다. - jbake는 빌드 시 가장 먼저 Markdown 파일의 메타 데이터를 읽습니다. 이 메타 데이터에서는 각 페이지에서 쓸 수 있는 지역 변수 정의, 타이틀 정의, 타입 정의 등을 할 수 있습니다. - 각 변수의 역할은 다음과 같습니다.

-title: 해당 문서의 제목이며 optional value입니다.
-date: 해당 문서의 작성 날짜이며 optional value입니다.
-type: 게시용인지 일반페이지인지에 대한 정보이며 Mandatory value 입니다. 
         값이 page일 때는 페이지 생성시 page.ftl 템플릿이 적용되고, 
         post일 때는 post.ftl 템플릿이 적용됩니다.
-status: 배포용인지 아닌지에대한 정보이며 optional value입니다. 값이 draft인 경우에는 빌드 시 
         해당문서의 html변환 결과물은 생성되지 않습니다.

[메뉴바 생성 및 동작흐름도] 9.png ① Markdown 파일의 본문 내용은 페이지의 body에 위치 ②우측 사이드 메뉴바- 메뉴 바로부터 active 상태에 놓여있는 메뉴항목의 리스트를 가져와서 메뉴바 생성 및 동작(이 과정은 Javascript 함수를 이용) 좌측 사이드 메뉴바- 현재 페이지로부터 제목 태그를 추출하여 리스트를 생성한 뒤 이것으로 메뉴바 생성 및 동작(이 과정은 Javascript함수를 이용) ③ Javascript를 통해 생성한 메뉴바 html 소스코드를 페이지에 삽입 이상으로 위와 같은 원리와 특징들을 바탕으로 메뉴바 관련 issue를 다음과 같이 해결해보았습니다.

◎ 두 번째 Issue 해결

3. 결과

Issue를 해결한 프로타입 모델을 TOAST Cloud API 문서에 적용해보았습니다.

3-1. 문서사이트 생성

아래 사진은 markdown 형태로 받은 TOAST Cloud API 문서파일로부터 html 형태의 문서사이트를 생성한 모습입니다. 기존 TOAST Cloud API 문서 사이트의 UI를 똑같이 구현한 모습을 보실 수 있습니다. 10.png

3-2. Git과 연동한 문서 버전 관리

① 각 브랜치별 build.gradle 의 내용을 수정합니다. beta 브랜치, dev 브랜치 등 각 브랜치별로 build.gradle에서 output의 제목을 다르게 설정해 줍니다. (ex. 'build/DEVoutput+Date' )

[Alpha 브랜치 build.gradle의 내용] 11.png ②문서 수정 후 git checkout을 통해 수정된 문서의 branch로 이동 후 push를 해줍니다. ③빌드 결과물은 build.gradle에서 정의해놓은 디렉터리에 생기게 됩니다. [생성된 결과물] 12.png

■ 고찰

현재까지 저희는 프로토타입을 통해 해당 CMS가 TOAST Cloud API 문서관리 시스템으로써의 임무를 수행할 수 있음을 확인하였습니다. 그러나 이것은 어디까지나 최소한의 자격 사항을 확인한 것일 뿐 성능과 효율, 보안을 전혀 고려하지 않은 시제품입니다. 따라서 이제는 저희가 선정한 CMS가 제 기능을 잘~~~ 수행할 수 있게끔 효율성을 고려하는 작업이 필요합니다.저희는 '문서관리의 편의성', '빌드속도'의 관점에서 JBake CMS의 앞으로의 개발 방향에 대해서 고찰해 보는 시간을 가져보았습니다.

1. 성능측정

JBake CMS의 성능을 측정하고 부족한 점을 파악합니다. 참고로 성능의 우수함과 부족함은 API 문서용 CMS로 잘 알려진 ReadTheDocs라는 CMS와 비교함으로써 그 정도를 가늠하도록 하겠습니다. 비교사항은 다음과 같습니다.

    1. 빌드 속도(github에 push했을 때 결과물 생성까지 걸리는 시간)
    2. 문서작성 용이성
    3. 문서관리 편의성

① 빌드속도

② 문서작성 용이성

type = page
~~~~~~

Markdown 파일 최상단부에 위에 있는 단 두줄만 추가해주면 됩니다. 이정도의 불편함은 감수할만한 사항이라 생각합니다. 만약 이마저도 불편하다고 생각되어 메타데이터를 전혀 기재하지 않도록 하고 싶다면 Jbake의 bin 파일에서 이와 관련된 소스코드를 찾아 type변수의 값이 항상 page가 되도록 함으로써 해결할 수 있을 것입니다.

③ 문서관리 편의성

JBake & JenkinsReadTheDocs
버전 관리각 브랜치마다 알맞은 build.gradle파일을 작성해 주어야 함대쉬보드를 통해 편리하게 버전 관리 가능
문서 제공HTML형태의 사이트 문서만 제공HTML뿐만아니라 PDF, ePub형태의 문서도 제공
환경 설정JBake와 Jenkins 두 가지의 기능을 이용한 것이므로 초기에 환경구성작업 필요자체적으로 모든 기능을 지원하므로 별도의 환경구성작업 필요 없음

[표 2] 두 CMS간 편의성 비교

※ 비교 정리

JBake & JenkinsReadTheDocs
빌드 속도빠름(ReadTheDocs보다 4배 이상)느림
문서 작성 용이문서 작성 시 메타데이터 2줄 추가 필요주의사항 없음
문서 관리 용이초기 환경 구성 필요모든 문서관리 기능을 자체적으로 지원하기 때문에 별도의 환경 구성 필요 없음

[표 3] 두 CMS 최종 비교

※ 최종고찰

JBake는 혼자서는 제대로 된 문서 관리의 기능을 하지 못하는 완전하지 않은 CMS입니다. 따라서 JBake의 부족한 기능을 보완해 줄 수 있는 다른 오픈소스 tool과 결합하여야 합니다. 이번에 저희는 Github 연동을 통한 문서관리를 하기 위해 Jenkins와 결합하였고 만약 현재 가지고 있지 않은 기능 중 문서 관리하는데 필요한 것이 있다면 또다시 유용한 tool을 찾아서 결합하여야 할 것입니다. ReadTheDocs, Hippo, Swagger, Wordpress와 같이 그 자체로 완전한 문서관리 기능을 할 수 있는 CMS들이 Jbake보다는 풍부하고 다양한 기능을 제공해 줄지는 모릅니다. 하지만 모든 것에는 등가 교환(trade off)가 있는 법! 부가적인 기능이 많아지게 되면 그만큼 SW는 무거워지기 마련이고 이것은 성능저하로 이어질 수 있습니다. 굳이 필요하지 않은 것들 때문에 중요한 필수 기능이 악영향을 받는다면 좋지 않습니다. CMS가 반드시 모든 기능을 다 가질 필요는 없습니다. 본인이 의도한 기능만 가지고 있으면 됩니다.이러한 맥락에서 저희는 API 문서관리를 함에 있어서 필요한 기능을 미리 정의해 놓고 그것에 맞는 맞춤형 CMS를 제작한 것이 의미있다고 생각합니다. Jbake를 이용하여 더욱 빠른 속도로 원하는 문서사이트를 생성할 수 있게 했으며, Jenkins를 이용하여 다양한 협업 도구와 연동한 문서작업 협업 및 배포가 가능하게끔 했습니다. 물론 각각의 기능을 지닌 tool들을 섞어놓았기 때문에 문서작성 시 불편함, 문서관리의 불편함과 같은 issue들이 발생하였습니다. 만약 이러한 issue 중에서 감수하고 넘어갈 만한 것이 있다면 그냥 넘기고, 만약 필요한 기능이라 판단 된다면 기존 tool의 소스코드 수정 및 다른 오픈소스 tool과의 결합을 통해 기능을 추가함으로써 회사의 의도에 맞는 CMS를 만든다면 좋은 CMS가 탄생할 수 있을 것으로 생각합니다.이상 이번 인턴 기간동안 study하였던 내용을 마치겠습니다. 긴 글 읽어주셔서 감사합니다~