Spring Rest Docs 세팅하기!

1. 들어가며

API를 만드는 것도 중요하지만 또 다른 중요한 것이 있습니다. 바로 API 문서를 만드는 것입니다. API를 만드는 목적 자체가 다른 누군가가 사용하기 위해서 만드는 것이기 때문에 API를 어떻게 사용하는지에 대한 API 문서를 만드는 것은 아주 중요한 일입니다. 

 

API를 만들기 위해서 사용하는 다양한 툴이 있습니다. 우리나라에서는 Swagger와 Spring Rest Docs를 많이 사용하는 것 같습니다. 각자 일장일단이 있기 때문에 무엇이 더 좋다라고 단정짓기는 어렵습니다. (다만 Spring Rest Docs 자체가 이름에서 Spring이 들어가는 것처럼 Spring 진영에서 좀 더 밀어주는 거 같기도...)

 

Spring Rest Docs는 테스트코드를 작성함으로써 API 문서를 만드는 방식을 채택하고 있기 때문에 테스트코드를 작성을 강제(?)하는 장점이 있는 반면에 초기 세팅이 조금 복잡하다는 단점도 있습니다.

 

이번 포스팅에서는 조금 복잡하다는 Spring Rest Docs 세팅에 대해 작성해보려고 합니다.

 

2. Spring Rest Docs 세팅하기

지금부터 나오는 내용은 Spring Rest Docs 공식문서에서도 확인할 수 있습니다. (링크는 2.0.7 버전 문서입니다.)

 

(1) build.gradle 추가

• asciidocVersion은 dependency에서 추가할 라이브러리 버전에 들어갈 버전을 변수처럼 따로 빼 놓은 것이라 생각하면 됩니다. 
• asciidocVersion은 스프링부트 버전이 아니라 Spring Rest Docs 버전을 넣어줘야 합니다.

 

• dependency 부분에 추가해주면 됩니다. 
• ${asciidocVersion} 부분이 위에서 만든 ext에 있는 변수가 들어갈 자리입니다.

 

• bootJar 부분은 공식문서에 나와있는대로 했을 때 제대로 되지 않았습니다. (이유 아시는 분은 댓글로 부탁드립니다..)
• 그래서 호돌맨님의 요절복통 개발쇼 강의에서 호돌맨님이 하시는 방법대로 했습니다.

 

(2)  테스트코드 작성

서두에서 언급하였듯이 Spring Rest Docs는 테스트코드 기반으로 API 문서가 만들어지기 때문에 테스트코드를 작성해야합니다. 임의의 테스트코드 클래스를 만들어 주는 것이 좋습니다. 

코드는 다음과 같이 세팅을 해주시면 됩니다.

 

이렇게 세팅을 하고 난 후 실제 테스트코드 케이스를 작성을 해 보겠습니다.

 

테스트코드를 실행을 시키고 테스트가 통과가 된다면 build/generated-snippets/index 디렉토리에 asciidoc이 생성되어있는 것을 확인할 수 있습니다.

각 파일들은 파일의 제목에 맞게 해당 API가 어떤 요청을 보내고, 응답을 보내는 지 등의 정보가 담겨져 있는 ascii 문서입니다. 

 

(3) 생성된 스니펫 사용하기 위한 세팅

src/docs/asciidoc 디렉토리를 직접 생성해준 후 index.adoc 파일을 생성해줍니다. 

 

index.adoc 파일에는 스니펫 경로에서 어떤 것을 가져올지에 대해 세팅을 해주면 됩니다.

• 빨간색 네모의 index/ 뒤에 있는 부분들이 위에서 확인한 generated-snippets/index 디렉토리에 있는 파일들입니다. 여기에 넣은 파일들만 실제 API 문서에서 확인할 수 있습니다.
• =, ==, :toc: 이런 표시들은 ascii 문서 문법입니다. 마크다운하고는 조금 달라서 인터넷에서 찾아본 후 작성하시면 될 것 같습니다. 인텔리제이의 경우에는 ascii 문서 작성하면 오른쪽에 바로 미리보기 화면을 띄워주는 플러그인도 있으니 설치하시면 문서 작성이 좀 더 용이할 것 같습니다.

 

여기까지 세팅을 마치신 후 그래들로 bootJar를 한 번 돌려주시면 src/main/resources/static 디렉토리에 index.html 파일이 생성이 됩니다. 

 

그리고 애플리케이션을 실행시켜주신 후에 localhost:{자신이 쓰고 있는 포트번호}/docs/index.html로 들어가시면 API 문서 페이지가 나오게 됩니다. (ascii 문서를 수정하시게 되면 bootJar를 다시 해주시고 애플리케이션을 다시 돌려줘야 업데이트 반영이 됩니다.)