개발과 문서의 싱크를 맞추기 위해
현재 회사에서의 개발은 개발을 먼저 하고 개발 문서를 작성하는 방식으로 진행하고 있습니다. API를 개발하고 개발한 API를 토대로 문서를 작성하는 방식이죠. 코드로 기능을 구현해 내고 API 문서를 작성할 시점이 되면 회사의 양식에 따라 API 문서를 MarkDown에 수기로 작성했습니다.
그런데 이번에 Open API Specification에 맞춘 API 문서를 작성하기 위해 StopLight라는 API 문서 작성 도구를 지원받게 되었습니다. 잠깐 OAS에 대해 짚고 넘어가자면 OAS는 Open API Specification인데 이는 개발을 하다 보면 한 번쯤 마주치는 Swagger라고 불리는 문서를 작성하는 규격이기도 합니다. 일반적인 경우 Swagger 문서를 직접 수기로 작성하지는 않을 것입니다. Framework 레벨에서 개발자가 만들어낸 API를 자동으로 Swagger 문서로 생성해 주기 때문입니다.
(다시 돌아와서) StopLight를 도입하면서 OAS 규격에 맞춘 문서를 작성할 수 있어 조금 나아졌지만 여전히 수기로 작성해야 되는 문제는 존재했습니다. 조금 시간이 지나 보니 이 문제는 다음과 같은 문제점을 야기했습니다.
개발된 API와 StopLight 문서 간의 차이가 존재한다
해결하는 제일 좋은 방법은 API를 개발하면 이를 Swagger 문서로 자동화해 주는 것이지만 앞서 말씀드렸듯 그러지 못하는 상황이기 때문에 개발된 API와 StopLight 문서 간의 차이를 빨리 확인하는 방법을 고민하게 되었습니다.
어떻게 풀 수 있지?
문서 간의 차이를 확인하는 방법에 대해 고민을 하고 있던 찰나 StopLight도 Github와 연계해서 사용할 수 있다는 점을 알게 되었습니다. 개발된 API도 Github Repository에 존재하고 있으니 이 두 Repository의 내용을 비교하여 개발이 완료된 Repository를 기준으로 아직 어떤 API 문서들이 StopLight에 존재하지 않는지를 판단할 수 있게 되는 것입니다.
비교하는 방식을 간단히 써보자면 다음과 같습니다.
1. API개발이 완료된 Github Repository에서 EndPoint 정보 추출
2. StopLight와 연계된 Github Repository에 작성된 모든 API 문서(json or yaml) 읽기
2-1. Github Repsitory에서 읽어 들인 API 문서에 정의된 EndPoint 정보 추출
3. '1'과 '2-1'을 비교하여 1에만 존재하는 경우 아직 API 문서가 나오지 않는 것
두 EndPoint를 비교하기 위해 구현해야 될 로직에서도 신경 써야 될 점이 존재합니다. '1'번 방식에 에서 읽어 들인 EndPoint와 '2-1'방식에서 읽어 들인 EndPoint는 서로 URI를 나타내는 방법이 다르기 때문에 이를 맞춰줘야 하는 작업이 추가로 필요로 하긴 합니다.
그러나 이 정도면 개발과 문서의 차이를 빨리 확인하고 누락된 문서가 무엇인지 빨리 파악하는데 부족함은 없었습니다.
이제 결론을 적어보고자 합니다.
이번에 경험한 사례에서는 어떤 문제들은 완벽하게 해결할 필요가 없을 수도 있다는 생각이 듭니다.
마치 API 문서 자동화를 위해 지금의 방식을 다 엎어버리고 새로운 기술을 도입하는 것보다 주어진 상황에서의 무엇을 하려는지 잘 인지하고 이를 해결하기 위한 정답이 아닌 자신만의 해답이 내리는 것이 곧 개발하는 재미가 아닐까 합니다.
