토스의 SLASH 22 영상을 보다가 배포 관련 설명에서 "...Rest Docs 테스트를 거쳐 사내 API 카탈로그에 게시하고..."라는 말이 귀에 들어왔습니다. 뭔가 문서화 이야기를 하는 것 같은데 처음 들어보는 표현이라 찾아보았습니다.
구글 검색에서 REST Docs 사이트가 가장 먼저 노출되고 그 다음에 나오는 것은 국내 개발자들이 작성한 글이었습니다. 배민 정산시스템 API 문서를 위키에서 Rest Docs로 전환했다는 글이 가장 처음에 나오고(아마 워낙 인기 있는 글이라 그런가 봅니다) 그 외에도 꽤 많은 글이 나옵니다. 한국어가 아닌 글을 찾으려면 한참 밑으로 내려가야 합니다. 그렇다면 이미 많은 곳에서 API 문서를 작성할 때 REST Docs를 사용한다는 거 같네요. 하지만 WTD 슬랙에서도 들어보지 못한 것 같고(물론 WTD 슬랙에 워낙 많은 글이 올라와서 보지 못했을 수도 있긴 합니다) 주변에서도 REST Docs를 사용한다는 이야기는 못 들어본 것 같습니다.
그래서 이게 최근에 나와서(현재 안정 버전이 2.0.7이니) 몰랐나보다 싶어 찾아보니 출시된 시점은 2015년입니다.
https://spring.io/blog/2015/10/07/spring-rest-docs-1-0-0-release
Spring REST Docs 1.0.0.RELEASE
<p>I’m delighted to announce that <a href="https://github.com/spring-projects/spring-restdocs">Spring REST Docs</a> 1.0.0.RELEASE has been released. It’s available from Maven Central and our <a href="https://repo.spring.io/release">release repository</
spring.io
첫 번째 문장을 보면 이게 어떤 목적을 가지고 만든 것인지 확인할 수 있습니다. "RESTful services를 문서화하는 것을 도와주는"이라고 설명하고 있습니다. Asciidoctor(https://asciidoctor.org/)를 사용해 직접 작성한 문서와 Spring MVC 테스트 후 만들어지는 스니펫을 조합해 문서를 만들어준다고 합니다.
그 이전에는 Swagger(2011년 출시)를 주로 사용했는데 확장이 어려웠나 봅니다. Swagger를 사용하면서 불편하거나 답답했던 부분을 보완해주는 도구로 만든 듯합니다.
지금(2.0.6 버전)도 기본적인 목적은 바뀌지 않았습니다. Spring MVC Test 외 WebTestClient(https://spring.getdocs.org/en-US/spring-framework-docs/docs/testing/integration-testing/webtestclient.html)와 REST Assured(https://rest-assured.io/) 정도 설명만 추가된 정도입니다.
REST Docs를 사용하면 실제 코드와 문서를 일치시킬 수 있습니다. 이것이 가장 큰 장점이겠죠. 사실 기술 문서의 문제점 중 하나가 실제 구현(코드)과 다르거나 업데이트가 느리다는 점이니깐요.
이제 Getting Started 문서를 보면서 따라가보려 했는데 기본적으로 스프링 프레임워크에 대한 개념이 부족하다 보니 따라가다가 뭔가 막히는 부분에서 더 이상 나아가지를 못하는군요(테스트하고 파일 생성되는 부분까지는 확인했는데 뭔가 참조 오류가 나서 더 이상 진행이 ㅠㅠ)
https://spring.io/guides/gs/testing-restdocs/#scratch
일단 뭔가요? 라는 궁금함을 푸는 정도에서 글을 마무리합니다.
* Getting Started 문서를 모아놓고 15분에서 30분 정도 튜토리얼 형태로 따라갈 수 있도록 구성해놓은 것이 인상적입니다.
