지난 포스팅에서는 데이터를 수급하며 전처리 과정을 거쳤고, Filebeat와 Logstash를 거쳐 Elasticsearch에 인덱싱 하는 것까지 알아보았다. 앞선 포스팅에서 이야기했지만 단순하게 데이터를 시각화 도구를 이용해서 대시보드를 만드는 게 아니라 데이터가 추가되면 만들어둔 대시보드에 자동으로 반영되는 흐름을 만들고 싶었다. 마침 파이프라인을 이틀 전에 만들었기 때문에 그동안의 빠진 데이터를 추가해야 하는 상황이다. 이 경우 Filebeat-Logstash-Elasticsearch 가 실행 중이라면 앞서 작성했던 파이썬 스크립트만 한번 실행해 주면 이틀 치 데이터가 파이프라인을 거쳐 Elasticsearch로 인덱싱이 된다. 즉, 별도로 데이터를 가져와서 재 가공하고 추가하는 다소 까다로운 작업이 미리 만들어둔 파이프라인 덕분에 한 번의 스크립트 실행으로 손쉽게 처리가 됨을 알 수 있다.

　이제는 쌓여있는 데이터를 가지고 시각화를 해볼 차례이다. ElasticStack에서는 Kibana라는 강력한 시각화 도구를 제공하는데 이번 포스팅에서는 Kibana를 이용해서 대시보드를 만드는 방법에 대해 알아보려 한다.

Visualize

　Elasticsearch에 인덱싱 되어있는 데이터들은 기본으로 제공되는 REST API를 통해서 조회할 수 있고 JSON 형태로 결과가 나오기 때문에 이를 가지고 다양하게 시각화를 할 수도 있다. 하지만 Kibana에서는 데이터를 조회하고 UI로 표현하는 일련의 모든 행위를 클릭 몇 번으로 할 수 있게 해주기 때문에 전문가가 아니더라도 조금만 만져보면 누구나 만들 수 있다.

　버전업이 되면서 비쥬얼라이즈를 만드는 첫 화면 또한 변화가 생겼다. 기존에는 어떤 유형의 비쥬얼라이즈를 선택할 것인지에 대해 선택하는 화면부터 나왔는데 만드는 걸 보다 편리하게 도와주는 Lens, TSVB 같은 기능들이 먼저 반겨준다. 이 기능을 통해서 만드는 방법도 괜찮지만 보다 명시적으로 만들고 싶으니 하단에 Aggregation based을 선택해서 원하는 비쥬얼라이즈의 타입을 선택해 보자. 이후 생성되어 있는 인덱스를 선택하면 본격적으로 비쥬얼라이즈를 그릴 수 있는 화면이 나오는데 대시보드 화면 기준으로 만들어야 할 항목별로 살펴보자.

전체 수

　확진자, 사망자, 격리 해제의 총합을 표현하려 한다. 이렇게 ‘숫자’를 표현하려 하는 경우 Metric을 활용하곤 한다. 우측에서 Aggregation 방법을 ‘sum’으로 설정하고 필드는 유형별로 각각 선택해 주자. 아래 ‘Add’버튼을 눌러 확진, 사망, 격리 해제 수를 모두 표시한 다음 저장을 눌러준다. Label을 지정하지 않으면 어떤 형태로 Aggregation을 했는지를 Label 영역에 보여주는데 그게 보기 싫다면 원하는 텍스트로 지정해 주는 것도 방법이다.

최근 수

　확진자, 사망자, 격리 해제의 ‘최근 데이터’를 보여주는 게 목적이다. 이 경우 Aggregation을 Top Hit으로 선택하면 필드를 선택할 수 있게 되는데 하루의 데이터가 총 18 row이기 때문에 (서울, 부산, …, 제주, 검역) 18 row 을 전부 더한 값이 하루 기준의 합계가 된다. 여기서 정렬을 날짜 기준 내림차순으로 해줘야 가장 최근 데이터의 합계가 되는 점도 신경 써야 한다.

각 타입별 합계

　지역별로 타입별 수를 보기 위해 Pie 타입으로 선택하여 진행한다. 타입별(예로 들어 확진이면 confirmed)로 합계를 구하기 위해 Aggregation을 ‘sum’으로 설정하면 빈 원이 나오지만 각 지역별로 차트를 잘라서 봐야 하기에 하단의 Buckets의 Add를 누르고 regieon의 필드를 Terms Aggregation 한다. 18 row의 데이터가 전부 보여야 하기에 정렬 개수를 늘리고 option 탭에서 보는 취향에 알맞게 설정값들을 바꿔준다.

타입별 추이

　확진, 사망, 격리 해제 중에 사망을 제외하고 나머지 둘은 데이터의 크기가 크고 변화량이 비슷하기 때문에 x축은 시간으로 설정해두고 사망은 막대로, 나머지 둘은 라인으로 한 화면에서 표현하면 이 3가지 데이터를 한눈에 보기 좋을 것 같았다. Vertical bar 을 선택하고 x축(Buckets > X-axis)은 데이터 타입인 convert_date로 설정한다. 다음으로 사망은 매일 몇 명 사망했는지 뚜렷하게 보기 위해 그냥 sum으로, 나머지 둘은 누적 합계가 더 의미 있어 보일 것 같아 Cumulative Sum으로 Aggregation을 한다. 한 화면에서 3가지의 데이터를 보여주기엔 다소 y 축의 크기가 맞지 않으므로 확진, 격리 해제를 별도의 y 축(Y-axes)으로 ‘Metrics & axes’탭에서 설정해 준다. 다음으로 각 항목의 범례를 위로 표시하여 보다 보기 편하게 배치한다.

　얼마 전에 필자의 블로그를 보고 어느 교육 기관에서 ElasticStack에 대한 강의 요청이 들어왔다. 사실 관련 기술에 대해 지식이 아주 깊고 해박한 게 아니라서 약간의 반감부터 들었지만 ElasticStack을 전혀 모르는 사람들 기준으로 어떻게 돌아가는지에 대해서만 간단하게 소개하는 정도로 하면 된다고 하여 조심스럽지만 떨리는 마음으로 열심히 준비를 하기 시작했다. 그런데, 이런저런 이유로 갑자기 강의를 할 수 없게 되었고 그간 준비했던 내용들이 너무 아쉽지만 아무 소용이 없게 되어버렸다. 그냥 중단하기엔 아쉬운 마음이 너무 커서 준비했던 내용 중에 ‘데이터를 가지고 대시보드를 만드는 부분’은 누군가에겐 도움이 될까 싶어 블로그에 정리를 해보려 한다.

강의를 준비한 올해 1월 중순엔 Elasticsearch 버전이 7.10.2이었는데 블로그를 쓰고 있는 지금은 벌써 7.11으로 버전 업 되었다. 내가 아는 오픈소스 중에 버전업이 가장 빠른데 그렇다고 기능이 확 바뀌거나 습득하기 어렵게 바뀌진 않았다. 그만큼 사용자가 무엇을 원하는지 명확히 알고 작은 단위로 조금씩 바뀌어 가는 모습이 꽤 인상적이다.

　작년 초부터 코로나19 바이러스가 전 세계적으로 퍼지기 시작했고 아직까지도 진행 중이다. 나도 전염되는 건 아닐까 하는 두려움에 어디에서 얼마나 발생했는지를 확인하기 어렵던 시절 우리나라의 뛰어난 개발자들은 누가 시키지도 않았는데 정말 감사하게도 그 현황을 한눈에 볼 수 있도록 여러 유형으로 코로나19 바이러스 대시보드를 만들기 시작한다. 그 덕분에 좀 더 현황을 보기에 편해졌고 더욱 조심하게 되는 계기가 되었다고 생각한다. 이제는 포털사이트나 각종 매체를 통해 손쉽게 코로나19 바이러스의 현황을 볼 수 있지만 이러한 데이터를 가지고 검색엔진이지만 대시보드를 구축하는데 훌륭한 기능을 가지고 있는 ElasticStack을 활용해서 ‘나만의 대시보드’를 만드는 걸 정리해보고자 한다. 본 포스팅의 일회성으로 데이터를 가지고 대시보드를 만드는 것에서 끝나는 게 아니라 지속적으로 데이터가 업데이트된다는 가정하에 전반적인 “파이프라인"을 구축한 뒤 대시보드를 만들어 두고 데이터만 갱신하면 자동으로 대시보드 또한 업데이트되는 것을 목적으로 한다.

글을 모두 작성하고 보니 양이 생각보다 길어져서 데이터를 조회하고 필터링하여 Elasticsearch에 인덱싱 하는 대시보드를 만들기 위한 일종의 “데이터 파이프라인"을 구성하는 부분과 만들어진 데이터 기반으로 Kibana의 다양한 기능을 활용하여 대시보드를 만드는 2개의 포스팅으로 나누어 정리해보겠다.

　최종적으로 만들게 될 대시보드의 모습은 다음과 같다.

대시보드 구성 준비

　예전에는 Elasticsearch, Logstash, Kibana 3가지를 가지고 ELK라 불리다 Beat라는 경량 수집기 제품이 등장하며 이 모든 걸 ElasticStack라 부르기 시작했다. (공식 홈페이지 참고) 먼저 어떤 목표와 어떤 순서로 대시보드를 구성할 것인지에 대해 정리해봐야겠다.

데이터

　데이터는 공공데이터 포털에서 가져오려다 조회를 해보니 누락되는 날짜도 있었고 원하는 데이터의 품질이 생각보다 좋지 않아서 다른 곳을 찾아봐야 했다. 그러다 간결하게 정리한 데이터가 깃헙에 공개가 되어 있어서 그것을 사용하려 한다. 해당 데이터는 https://coronaboard.kr/ 에서도 사용되는 데이터라고 한다. 

데이터 전처리(preprocessing)

　원하는 데이터는 위 깃헙에서 제공하는 데이터 중에 지역별 발생 현황. 해당 데이터를 살펴보면 요일별로 데이터가 ‘누적’되어 저장되어 있다. 즉, 서울지역 기준으로 2020년 2월 17일에 14명이 발생했고 2020년 2월 18일에 한 명도 발생하지 않았는데 14명으로 ‘누적’되어 저장되어 있다. 사실 이대로 해도 큰 문제는 없지만 어디까지나 별도의 가공 없이 최대한 원본 데이터(raw) 가 있어야 데이터 분석 시 다양하게 활용이 가능하기에 데이터를 분석하기 전에 전처리 과정이 필요했다. 정리하면, 집계 수가 누적되지 않고 날짜 기준으로 집계된 수만 있는 데이터를 원했다.

　필자는 주로 java를 가지고 개발을 하지만 가끔 간단한 스크립트성 개발은 python을 활용하는 편이기에 다소 이쁜 코드는 아니지만 데이터를 조작하려 아래와 같은 코드를 작성하였다.

 　이력서는 언제 쓰게 되는 걸까? 아주 일반적으로. 신입(학생)의 경우 대학을 졸업할 즈음 취업하고 싶은 회사로 지원하기 위해 작성하고, 경력(회사원)의 경우 이직을 마음먹고 가고자 하는 회사가 뚜렷하게 결정이 되면 그때 작성하게 되는 것 같다. 회사마다 정해진 형식이 있는 곳이라면 그 형식에 맞추어 작성하고 그렇지 않다면 나만의 기준에 맞추어 작성하게 되는 ‘이력서’.

　회사에 입사하고 정신없이 지내다 보면 이직을 생각하기 전까지는 ‘이력서’라는 존재를 자칫 잊어버리기 쉽다. 또한 구태여 시간을 할애하면서까지 써야 한다는 마음조차 잘 들지 않는다. 실제로 텅 빈 책상 앞에 앉아 하얀 A4지와 펜 한 자루만 가지고 써봐야지 하고 시작하면 내가 이제까지 뭘 해왔나 하며 잘 써지지 않기도 하고.

　그런 개발자로 괜찮은가 시리즈인 이번 포스팅에서는 개발자에게 있어 ‘이력서’란 무엇이고 언제, 왜 그리고 어떻게 써야 하는지에 대해 이야기해보고자 한다. 정보의 바다, 홍수처럼 쏟아지는 기술의 변화를 IT 최전방에서 온몸으로 맞서 싸우는 우리 개발자들에게 ‘회사’보다는 ‘나 자신’을 위해 하루를 살아갈 수 있는 ‘힘’이 되었으면 하는 마음으로.

들어가기 앞서, 본 포스팅은 이직을 권유하는 내용은 절대 아님을 밝힌다. 오히려 이력서 작성을 통해 현재의 직장에서 본인에게 더욱 집중하고 회사와 함께 성장했으면 하는 바람이다.

개발자에게 이력서란?

　우선 이력서란 무엇일까? 사전적 의미를 먼저 살펴보자. 위키백과에 따르면 “취직을 위한 면접의 기회를 얻기 위해 회사 등 조직에 제출하는 개인의 신상정보, 학력, 경력 등을 시간 순으로 요약 혹은 나열한 문서"라 나와있다. 여기에 추가로 우리 개발자들은 본인이 사용할 수 있는 ‘기술’이나 특정한 ‘경험’을 적으며 자신이 가지고 있는 기술적 가치에 대해 어필하는 경우가 대부분이다.

　사전적 의미로 보면 ‘내 정보’를 잘 요약해서 취업하고자 하는 ‘회사’에 전달하는 수단으로도 이해할 수도 있을 것 같다. 즉, 누군가에게 본인을 정보(혹은 실력)를 정리해서 알리는 수단 중에 하나로 볼 수 있는데, 과연 이 이력서에는 ‘알린다’라는 의미만 담겨있을까?

　필자가 생각하는 이력서의 정의는 ‘나를 알리는 수단’ 보다 ‘나를 가장 잘 아는 거울’이라 생각한다. 특히 개발자에게는 더욱더. 무엇을 개발해왔고 어떤 기술을 써 왔으며 어떤 경험이 있는지 어느 곳에 작성을 하지 않으면 더듬더듬 기억으로 나 자신을 알기엔 요즘은 봐야 할 정보가 많은 세상이 되어버렸기 때문이다.

왜 써야 할까?

　앞서 이력서를 ‘나를 가장 잘 아는 거울’이라고 말했다. 거울을 보고 얼굴에 뭐가 묻었으면 닦거나 옷차림이 별로라면 고쳐보는 등 ‘거울’은 나를 가장 잘 볼 수 있는 도구 중에 가장 좋은 물건이라 생각한다. 그런 의미에서 이력서는 단순하게 ‘Java 개발 N 연차’ 가 아닌 그동안 무엇을 해왔고 어떤 경험과 기술을 사용해 왔는지 정리를 하며 나 자신을 돌아볼 수 있는 훌륭한 도구라 생각한다.

　개발자 생활(정확히 말하면 회사 생활)을 하다 보면 개인 사업을 제외하고 회사가 추구하는 비즈니스의 목표를 위해 자의적이 아닌 타의적으로 임무를 할당받아 진행하는 경우가 대부분이다. 그러다 보면 소위 말하는 ‘찍어내기식 개발’을 하는 경우도 많고, 문제를 만날 경우 다양한 삽질로 해결은 하지만 제대로 이해하지 못한 채 일정에 치여 넘어가는 경우들도 있다. 그렇게 시간이 지나고 연말이 되어 한 해를 돌아보면 업무를 일정에 맞추어 진행하는 데는 성공하였지만 정작 본인에게 남은 건 장시간 컴퓨터 앞에 앉아 생긴 거북목과 점점 짙어져가는 다크서클뿐이다.

　이력서를 써야 하는 이유를 크게 두 가지로 꼽자면, 첫 번째로는 나를 알리는 수단(Personal branding)으로 활용할 수 있다는 점에서다. 잘 정리한 자신의 이력서를 공개해놓으면 취업의 기회가 생길 수도 있고 인적 네트워킹이 되어 생각하지 못한 ‘기회’를 얻을 수도 있기 때문이다. 두 번째로는 앞서 이야기 한 ‘나 자신을 돌아보기 위함’이다. 멀리 가려면 앞만 보지 말고 뒤도 돌아볼 줄 알아야 한다는 말도 있지 않은가. 이력서를 쓰다 보면 무엇을 해냈고, 어떤 걸 할 수 있고, 그런데 무엇이 부족한지 (자괴감이 들기도 하지만) ‘팩트’로 볼 수 있기에 보다 나 자신에게 집중할 수 있다는 점에서 꼭 이력서를 써봐야 한다고 이야기하고 싶다.

　그 어느 때보다도 정신없이 달려온 2020년. 하고 싶은 것도 많았고 큰 꿈을 꾸기도 했지만 현실의 벽 앞에 크게 좌절도 해보기도 하고. 갑작스러운 세상의 변화에 적응하랴 정신적으로 육체적으로 너무 많이 힘들었던 올해. 돌아보면 참 후회가 되지만 한편으론 시련과 좌절 속에서 여러 가지를 배웠던 그런 한 해를 보낸 것 같다.

　필자는 내년이 되면 이제 어느덧 개발자 생활을 한 지 9년 차가 된다. 보통 주니어라 함은 단순하게 이제 막 취업한 신입 또는 3~5년 차를 말하고 시니어는 연봉이 X 원을 넘거나 n 연차를 넘을 경우를 말하는 것 같다. 물론 각 회사마다 이 둘을 정의하는 기준이 다르겠지만. 그런데 필자는 주니어도 시니어도 아닌 그 사이에서 애매~한 연차. 중니어. 과연 나는 무엇을 해야 할까? 무엇을 해야 연차에 맞는 역할(?)이라고 할 수 있을까? 그리고 그건 누구에게 배워야 하고 누가 가르쳐 주기나 할까?

　매년 회고를 써왔다. 그럼에 연말이 되어서 연례행사처럼 작성하는 게 아닌 나에게 정말 필요한 방향으로 회고를 작성하려 한다. 단순하게 이런저런 일들이 있었고 ‘어쩔 수 없었네~’ 읊조리는 무의미한 회고보다 현실적으로 나 자신을 위해 변화해야 할 게 있으면 굵고 길게 계획을 세워보는 방향으로 해보고 싶다.

• 2019 회고
• 2018 회고
• 2017년엔 왜 없지..?
• 2016 회고

등장, 코로나-19

　세상이 변했다. 작년까지만 해도 미세먼지가 심하면 마스크를 쓰고 나가곤 했지만 코로나-19라는 전염병이 전 세계에 퍼지며 이제는 마스크 없이 살 수 없는 세상이 되었다. 늘 사무실에 나가 팀 동료분들과 이야기를 하며 밥도 먹고 회의도 하며 업무를 진행했지만 재택근무를 한지 어느덧 반년이 훌쩍 지났다.

　처음엔 집에서 편하게 일을 할 수 있어서 좋았다. 그러나 IT 회사에 근무하고 있지만 아직도 버벅거리고 어색한 화상회의와 더딘 업무 진행으로 인해 점점 시간이 지날수록 답답함은 극을 달했다. 출/퇴근 시간 등 업무이외에 필요한 시간이 사라지며 오히려 업무에 집중하는 시간은 많아졌다. 그에 반해 피로도는 집중한 업무시간에 비례하며 늘어났기에 나무늘보처럼 늘어지는 시간들 또한 많았던 것 같다. 지나고 보면 그러한 시간들을 잘 계획하고 움직였더라면 뭐라도 배우거나 달성했을 시간들인 것 같아서 약간 아쉬움이 남는다. 내년엔 계획하는 시간의 비중을 좀 더 늘리는 것으로.

　아무쪼록 코로나-19 바이러스가 없어지고 다시 예전으로 돌아갔으면 좋겠다. 그에 마스크 잘 쓰고 손 잘 씻고 사람 많이 모이는 곳은 피해야 하는 건 우리가 할 수 있는 해야 할 가장 큰일이겠지.

회사생활

서비스 전면 개편

　팀에 투입한 이후 가장 큰 규모로 서비스 전면 개편을 진행하였다. 거의 올해 내내 했다고 봐도 무방할 정도. 업무의 양도 많았고 스펙 또한 복잡하였지만 가장 크게 배울 수 있었던 부분은 모놀리틱 서비스에서 마이크로 서비스로의 아키텍처 변화를 시도했다는 점. 그리고 일반적인 Request - Response 식의 1차원적인 흐름에서 이벤트라는 행위를 기준으로 모든 프로세스가 영향을 받는 구조를 적용하며 고민했다는 점에서 여러 가지 인사이트를 얻을 수 있었다. 아무래도 중니어다 보니 주어진 기능을 개발만 하는 것보단 좀 더 높은 곳의 설계 관점에서 고민하는 연습을 하려고 했던 것 같은데 아직 부족한 것 같다.

　올해도 개발 문화를 개선하려는 노력도 하였다. CI를 재설치하고 다양한 개선을 통해 빌드 속도를 몇 배로 늘리기도 하였고, 단순/반복적인 업무들은 각종 봇들을 개발하여 업무 생산성을 올리기도 하였다. Sentry를 서버 레벨에 적용하여 무분별하게 발생하는 에러들을 그룹핑하여 우선순위에 따라 에러를 해결할 수 있는 구조를 만들기도 하였고, 소나큐브와 jacoco를 적용하여 코드 커버리지를 도식화하며 현재 모듈의 상태를 보여주기도 해보았다. 개발 문화의 개선은 겉으로 드러나진 않지만 잠재적인 문제들을 해결하는 데 가장 큰 효과를 준다고 믿기 때문에.

　‘애자일’ 이라고 하면 무엇이 떠오르는가? 잘은 모르지만 막연하게 생각을 해보면, 매일 오전 스크럼을 하고 진행 현황을 가시화하며 프로젝트를 성공적으로 이끄는 일종의 ‘프로세스’로 알고 있다. 좋다는 것도 들었고 도입을 하려 하지만 뭔지 모르게 잘 안되는 그것. 현업에 들어오면서 ‘애자일’ 도입의 성공/실패에 대한 이야기를 가끔씩 건너건너 들어만 본 수준이다. 이제는 주니어도 시니어도 아닌 중니어가 되어보니 알고리즘이나 패턴, 신기술도 중요하지만 팀과 프로젝트 전반의 건강하고 성공적인 진행을 위해서는 이러한 활동들이 중요하구나 하며 요즘 (올해) 뼈!저!리!게! 느끼는 중이다.

　마침 크리스마스 연휴를 앞두고 이 시국에 나가지도 못하는데 뭘 해야 하나 고민하고 있던 찰나 운명처럼 클린 애자일, 저자 로버트 C. 마틴이라는 책 추천을 받는다. 보통 필자는 읽고 싶은 책을 고를 때 중요하게 생각하는 두 가지가 있는데 표지와 추천인(혹은 리뷰어)의 대한 신뢰. 둘 다 너무 좋았기에 바로 인터넷 주문을 하였지만 그새를 못 참고 근처 서점에 들러 책을 사 온다.

갑.분.돈(키호테)

　풍차나 폭포를 공격해본 모든 프로그래머에게

　호기롭게 첫 장을 넘기는데 강렬하게 다가오는 문구. 옮긴이에 따르면 세르벤테스의 소설 ‘돈키호테’에서 주인공 돈키호테가 풍차를 공격하는 모습에서 온 표현이라 한다. 대부분 헛되고 무모한 싸움을 하는 사람들을 빗대어 이야기하며 바보 혹은 현실 부적응자로 갈음하는 표현으로 사용된다. 러시아 작가 이반 투르게네프는 햄릿을 사랑하기는 힘들지만 돈키호테는 사랑하지 않기가 힘들다는 이야기를 했다고 한다. 아마 저자는 고민보다는 행동을 중요하게 생각했던 돈키호테를 빗대어 현실에 안주하지 않고 건강한 개발 문화를 개선하려는 모든 프로그래머에게 조언과 박수를 보내려 했던 건 아닐까 싶다.

책의 구성

　페이지 수(230p)가 많지 않아서 가볍게 읽을 수 있겠다 싶었지만 다소 작은 글씨들로 구성되어 있어서 책을 잘 안읽었던 필자에겐 약간 부담으로 다가왔다. 하지만 내용들이 너~무 공감이 되어 마치 필자의 2020년을 오래전에 예견하고 미리 써둔것 같은 느낌을 받았을 정도라 아침 5시에 일어나 저녁 11시가 되어서야 다 읽을 수 있었다. 처음 들어본 용어나 이해가 잘 안되는 개념들도 있어 다음날 노트북을 옆에 두고 찾아가며 다시 읽기도 하였다. (그만큼 제대로 읽어보고 싶었다.)

　책 초반부터 저자는 이 책을 ‘선언’이나 ‘정의’ 가 아닌 애자일에 대한 ‘경험’을 토대로 오해를 바로잡는다라고 이야기하고 있다. 2001년 2월, 애자일 선언이 발표가 되었고 내년이면 20년이 돼가는 시점에 여러 가지로 변형된 ‘애자일 방법론’이 나왔지만 애자일의 기준을 다시 소개하며 본질을 흐려선 안된다고 이야기한다. (책이 부 제목이 Back to Bascis인 것을 보면 …)

　흥미진진한 책 내용 중에 아직까지도 머릿속에 남아있던 애자일과 자주 비교되는 ‘폭포수 모델’로 프로젝트를 진행한 부분을 필자가 이해한 대로 적어보려 한다. (너무나도 끔찍하게 공감되기에…)

　MSA 환경에서의 API 문서화는 어떤 식으로 구성하는 걸까? 예컨대, 모듈이 10개 있다고 하면 각 모듈마다 API 문서가 만들어질 테고 API 문서를 클라이언트에 제공하기 위해서 각각의 (10개의) URL를 전달해야 할 텐데 이게 과연 효율적일까? 물론 기능별로 URL이 분리된다는 장점이 있고 굳이 모아보자면 각 API 문서를 다시 한번 크롤링 하여 검색할 수 있도록 제공하는 것도 하나의 방법이 될 수 있다. 하지만 이러한 방법들은 요구 사항을 위한 별도의 작업을 하게 되니 일을 위한 일이 되는 것 같아 뭔가 아쉬웠다. 좋은 방법이 없을까?

고민의 시작

　한창 궁금증이 머릿속에서 지워지지 않았을때 Spring 한국 스프링 사용자 모임 페이스북 그룹에 문의도 해가며 방법을 찾아가고 있었다.

　필자와 함께 개발자의 인생을 시작한 멋진 친구들에게 정확히 올해 6월 초에 고민을 털어놓으며 좋은 방법이 없을지에 대한 논의를 했던 적이 있다. 그런데 친구 중 한 명이 잊고 있었던 그 이슈에 대해서 다시 꺼내며 URL 하나를 던져준다. 참 고마운 친구들.

Shout out 34. asuraiv, black9p

　올해 NHN FORWARD에서 진행했던 세션 중에서 MSA 환경에서 API 문서 관리하기: 생성부터 배포까지라는 제목의 내용이었고, 정확하게 필자가 고민했던 부분을 콕! 집어서 해결해 준 사례였다. 역시 세상엔 엄청난 고수들이 내가 고민했던 부분들을 이미(혹은 이후에라도) 고민하고 해결한 경우가 많다는 것을 느끼고 공유의 힘이 이렇게도 대단하구나 하며 놀라움을 금치 못하였다.

　이번 포스팅에서는 OpenAPI Spec 을 활용하여 Spring Restdocs로 만들어지는 문서를 Swagger UI에서 보는 흐름을 실제로 구현해 보고자 한다. 즉, Swagger 나 Spring Restdocs 뭐로 만들든 간에 OpenAPI Spec에 맞춰서만 만든다면 한곳에서 볼 수 있겠다는 희망이 보였다. 며칠 전 작성한 OpenAPI 와 Swagger-ui 포스팅을 본 독자들은 지금의 포스팅을 작성하기 위한 밑거름이었다는 사실을 눈치챘을 수도 있을 것 같다.

좋은 내용을 공유해 주신 (저의 고민을 완벽하게 해결해 주신) NHN FORWARD 발표자분께 이 포스팅을 빌어 감사의 인사를 보냅니다. :) 당장 팀 내에도 적용해봐야겠어요!!

Spring Restdocs에서 OpenAPI Spec 추출

　누가 또 친절하게 오픈소스로 만들어놨다. https://github.com/ePages-de/restdocs-api-spec 에서 관련 내용을 확인할 수가 있는데 해당 링크에서는 gradle 버전이고 https://github.com/BerkleyTechnologyServices/restdocs-spec 는 maven 버전이라고 한다. 마침 필자의 Github에 Maven 버전으로 SpringRestdocs를 세팅해둔 Repository 가 있어서 이를 활용해보고자 한다.

pom.xml 추가

　관련 dependency를 추가하자. jcenter라고 bintray.com 에서 운영되는 Maven Repository에 올려진 오픈소스이니 repository 도 추가해 주자.

<properties>
	<restdocs-api-spec.version>0.10.0</restdocs-api-spec.version>
	<restdocs-spec.version>0.19</restdocs-spec.version>
</properties>

<repositories>
	<repository>
		<id>jcenter</id>
		<url>https://jcenter.bintray.com</url>
	</repository>
</repositories>

<dependency>
	<groupId>com.epages</groupId>
	<artifactId>restdocs-api-spec</artifactId>
	<version>${restdocs-api-spec.version}</version>
	<scope>test</scope>
</dependency>

<dependency>
	<groupId>com.epages</groupId>
	<artifactId>restdocs-api-spec-mockmvc</artifactId>
	<version>${restdocs-api-spec.version}</version>
	<scope>test</scope>
</dependency>

위의 dependency에서 제공해 주는 모듈로 테스트의 SpringRestdocs를 만들었다면 OpenAPI Spec 을 만들어 주는 plugin 또한 추가해 주자

<pluginRepositories>
	<pluginRepository>
		<id>jcenter</id>
		<url>https://jcenter.bintray.com</url>
	</pluginRepository>
</pluginRepositories>

<plugin>
	<groupId>com.github.berkleytechnologyservices.restdocs-spec</groupId>
	<artifactId>restdocs-spec-maven-plugin</artifactId>
	<version>${restdocs-spec.version}</version>
	<executions>
		<execution>
			<goals>
				<goal>generate</goal>
			</goals>
			<configuration>
				<specification>OPENAPI_V3</specification>
				<format>JSON</format>
				<outputDirectory>${project.build.directory}/classes/static/docs</outputDirectory>
			</configuration>
		</execution>
	</executions>
</plugin>

위 plugin 설정을 보면 format 을 JSON으로 한 것을 볼 수 있는데 YAML로도 만들 수 있다. 자세한 사용방법은 위에서 명시한 링크를 참고해보는 게 좋을 것 같다.