Spring REST Docs 도입 이유

회사에서 새로운 프로젝트를 시작하는데 REST API 설계부터 하고 api 문서를 뽑아내기 위해 REST Docs를 적용하기로 했다.

 

Spring REST Docs?

- Asciidoctor를 사용해서 API 문서를 생성하도록 돕는 것이다.

 

나는 여러 사이드 프로젝트를 하면서 API 문서를 전달하기 위해 swagger, postman, notion 등을 사용했었다.

이번에는 REST Docs를 적용해야 해서 오랜만에 글을 써본다.

 

우선 여러 방법으로 api 문서를 뽑아내면서 느낀 점을 간단히 소개해보겠다.

 

swagger

- 실제 코드에 어노테이션들이 추가 되면서 문서가 생성된다.

- 가독성 측면에서 여러 어노테이션이 달리면 지저분해 보일 수 있다. 실제로 지저분해 보이긴했다.

- 하지만 많이 쓰이는 이유는 쉽기 때문이라고 생각한다.

- 실제 서버가 구동되면서 api를 테스트 해볼 수 있는 것은 큰 장점이라고 생각한다.

 

postman

- 테스트 코드를 많이 사용하기 전에는 api 테스트를 postman을 통해서 했었다. ( 테스트 코드 작성이 미숙해 아직도 많이 사용 중이긴 함...)

- 직접 테스트를 하면서 api doc을 생성해서 문서를 뽑아내 줄 수 있다.

- 이것 또한 서버가 구동되면 api를 테스트 해볼 수 있다.

- 사실 별다른 단점은 나는 잘 모르겠다.. 있다면 알려주세요ㅎㅎ

 

notion

- 노션은 좋은 어플리케이션임은 분명하지만 api 문서를 제공한다는 목적에는 부합하지 않는 것 같았다.

- 일일이 쳐줘야 했으며 사실 복붙을 엄청했었음..ㅎㅎ 

- 회의록이나, 스프린트 관리할 때는 되게 좋았었음!

---

 

그래서 왜 REST Docs를 채택했나!

 

우선 문서를 자동화하는 것을 원했다. 또한, 깔끔한 api 문서를 원했으며 깔끔한 코드를 작성하기로 하였다.

그리고 test code를 중요시하여 test coverage를 높이기로 했다. 

이러한 이유는 REST Docs를 가리켰다. test code를 작성해야 문서를 자동화시켜주기 때문이다. 

이는 생산성 저하로 이루어질 수 있지만 test code를 열심히 공부하고 적용할거니까..ㅎㅎ

나는 실제로 문서와 함께 테스트 해볼 수 있는 환경을 원했지만 결국은 api "문서"이기 때문에 여러가지 이유로

채택하게 되었다.

 

다음에는 REST Docs를 적용하는 포스팅으로 와보겠다! 빠잉~