Spring RestDocs 적용기..

처음 Musicat 프로젝트를 진행할 때는 Rest API 서버를 구축하면서 왜 써야하는지 모르고 갖다 쓴 것도 많았다.

 

대표적인 예가 Swagger-UI 그리고 RestDocs 였다.

 

우리가 처음 REST API 서버를 개발하게된 것은 좀 갑작스러웠는데, 학원에서 계속 MVC 구조로만 개발하다가 마지막에 갑자기 각 조마다 REST API 서버로도 개발하는 기능이 있는 것이 좋겠다고 하셔서 급하게 공부해서 추가하게 되었다.

 

그 때 학원에서 요구한 스펙 중 하나가 바로 문서 자동화였는데, 처음에는 적용하기 쉬운 Swagger-UI를 제안하셨고 우리는 '문서 제공겸 테스트도 제공하는 툴' 정도로만 이해하고 우선 적용했었다.

 

하지만 사실 우리는 백엔드-프론트 모두 우리가 개발했기 때문에..

자기가 맡은 API 스펙은 자기 머릿 속에 들어있어서 사실상 Swagger-UI는 전혀 필요하지가 않았다.  (API 테스트는 Postman이 더 편해서 테스트할 때도 필요가 없었다.)

 

플젝이 다 끝나고 나서 Swagger-UI 말고 RestDocs를 적용해보는 것이 어떠냐고 하셔서 또 부랴부랴 알아보았고,

비즈니스 코드를 깔끔하게 유지할 수 있고 테스트 코드 기반으로 돌아간다는 점이 확실히 더 나아보여서 적용했었다.

 

그러나 그 때도 그저 적용해보는 것에 끝났고 실제 사용자에게 노출될 화면이라던가 이런 것까지는 잘 고려하지 않았었다. 

API 문서에 대해 이론적으로는 알았지만 그 필요성에 대해 몸소 느껴보지 못했기에 '이정도면 됐지' 라고 생각했던 것이다.

 

하지만 Angry-Bank를 진행하면서 프론트/백엔드 파트를 나눠서 프론트 개발자분들과 협업하며 API문서를 노션에 직접 작성해주는 방식으로 진행했는데, 아주 많은 것을 느낄 수 있었다.

 

그 중 가장 크게 느낀 것은 두 가지였는데,

 

1. API문서는 생각보다 자세하게 써야한다... 자세하면 자세할수록 좋다...! (대충 쓰면 프론트쪽에서 문의가 많이 들어오거나 프론트분들이 작업하실 때 불편하다.) 

 

2. 코드를 고치고나서 API 문서를 수정해주는 것을 까먹는다면 그것은 누군가에게 작업 시간 피해로 돌아간다! (그치만 새벽에 졸면서 작업을 하고나면 높은 확률로 까먹어버린다.)

 

결론 : API 문서는 모자란 정보 없이 적고, 자주 수정해줘야한다.

 

이전에 문서 자동화에 대해 공부할 때 여러 번 읽었던 내용이었다. 하지만 직접 해보니 정말 왜 자동화를 해야하는지에 대해 뼈저리게 느낄 수 있었다. 

 

그래서!

오랜만에 musicat-audio REST 서버에 적용했던 문서를 다시 들춰보았을 때 깜짝 놀라고 말았다. 

테스트 코드를 작성하고 스펙을 뽑는 것까진 해놨지만, 실제 API 문서를 출력해주는 화면은 만들지 않고 있었던 것이다. 

 

변명을 하자면... 당시의 우리는 문서를 보는 입장이 되어본 적도, 문서를 보여주는 입장이 되어본 적도 없었던지라 '오, 테스트 코드도 잘 돌아가고 스펙도 adoc 파일로 잘 나왔네.' 까지만 생각하고 말았던 것 같다... ^^;;;

 

이제라도 알게 되어서 다행이다... 라고 생각하며 부랴부랴 API 문서 출력 화면(html)을 만들었다.

RestDocs 적용법 정리 : https://fidget278.tistory.com/54

Spring Rest Docs 적용 (Maven)

 

html 까지는 순조롭게 만들었는데, 실제로 배포했을 때 docs/index.html 로 접근하지 못하는 문제가 있었다.

우리는 war로 패키징하여 외장 톰캣으로 배포하는데 아마도 외장 톰캣과 경로가 겹쳐서 그런 것 같았다.

docs/index.html 로 접근하던 것을 restdocs/restdocs-index.hmtl 로 고쳐주니 잘 되었다. 

 

이제 테스트 코드로 뽑은 문서들은 전부 html 파일에 담아주는 작업을 해야한다.

문서 수정을 까먹는 일은 없어지겠지만 사실 이런 셋팅 해주는건 좀 시간도 많이 걸리고 불편하긴 하다... 역시나 100% 편한 일은 없는 것 같다..