Spring RestDoc

이번에 새롭게 토이 프로젝트를 진행하면서 Spring RestDoc을 적용해보고자 공부했던 내용을 정리해봅니다.

 

Spring RestDoc 먹어본 이유

---

이전 프로젝트에서는 Swagger를 사용해서 문서화를 진행했는데, Swagger를 사용하면 직접 호출해서 응답 결과 받아보고 좋은데.. 좋은데?

 

매번 컨트롤러에 Swagger 의존성을 사용해서 문서화에 관련한 정보를 코드에 찍어 넣는 방식이 조금.. 거시기 했습니다.

단순 반복도 너무 많고 코드도 핵심 로직만 있는게 아니라 뚱뚱해지고 온전히 저의 시야에서는 그렇게 보였다구요..

 

Spring RestDoc을 사용하면 테스트 코드 작성을 통해 문서화를 진행할 수 있어서, Swagger를 사용해서 프로젝트를 진행했던 때처럼 테스트 코드 작성과 Swagger관련 코드까지 따로 작성하는 번거로움이 없어서 좋을 것 같다는 생각에 관심이 생겼습니다.

 

 

---

 

Spring RestDoc을 사용하기 위해 의존성을 추가해주고 gradle설정을 해주어야 하는데 gradle 7.0버전 이상부터는 

asciidoctor plugin을 'org.asciidoctor.jvm.conver'로 해주어야 build 이후 doc파일이 생깁니다.

 

테스트에 사용되는 restdoc관련 의존성을 추가해줍시다.

이제 build이후 생길 .adoc파일을 보관할 폴더 위치를 지정해줍니다. (지정해주기위한 전역 변수 선언)

(이 build후에 생긴 파일의 위치는 테스트할 때 custom으로 위치를 지정해줄 수 있습니다.)

 

asciidoctor을 실행할 때마다 기존 doc 파일들을 제거해주는 설정을 추가해주시고

build후에 build/docs/asciidoc에 생성된 파일들을 resource/static/docs밑으로 복사해주는 task를 추가해줍니다.

 

일단 크게 이렇게 설정을 하고 build후에 생성될 snippet들로 document를 구성할 .adoc파일을 만들어주면됩니다.

 

 

index.adoc에서 build/generated-snippets밑에 생성된 폴더에서 .adoc 파일을 읽어와 화면을 구성하는 마크업을 작성해줍니다. 

(asciidoc 기본적인 사용법 : https://narusas.github.io/2018/03/21/Asciidoc-basic.html )

 

일단 설정은 이정도로 해두고 이제 Spring RestDoc을 사용해볼게요 전부 다는 무리고,;; 몇개만 골라서 해봅시다.

 

그리고 아까 위에서 말씀드린 테스트 작성할 때 폴더 위치 커스텀하게 지정하는 것도 겸사겸사 할게요

 

저는 MockMvc를 사용해서 테스트를 작성할건데 이 mockMvc에 restdoc 설정을 해주겠습니다.

 

@ExtendWith에 RestDocumentationExtension을 지정해주고 매 테스트 이전에 Spring의 application context를 주입 받아 context 상태를 유지하고 restDocumentation을 인자로 넘겨 설정해줍니다.

 

그리고 @Test에서 andExpect로 검증 이후 andDo에서 document()를 지정해서 처음 설정한 build/generated-snippets아래 생성될 폴더의 이름을 지정해줍니다.

 

그리고 build하면 예상대로 build/generated-snippets/smaple에 생성이 되는 것을 확인할 수 있습니다.

 

 

이제 커스텀 폴더를 지정해보겠습니다. 전역적으로 설정한 폴더 위치가 있지만 테스트 마다 폴더의 위치를 다르게 구성하고 싶을 때 유용할 것 같네요.

 

우선 기존 @ExtendWith(RestDocumentationExtension.class)를 주석 처리하고 rest doc extention을 지정하기 위해 별도의 클래스에서 RestDocumentationExtension 객체를 생성해서 @RegisterExtension을 붙여주면 해당 필드 객체가 extension으로 적용되는데 이 클래스를 테스트에서 상속받아 사용하겠습니다.

 

 

이제 gradle clean build를 다시 실행해보면 

 

적용된 것을 확인할 수 있습니다.

 

그럼 이제 rest doc의 기능을 몇개 확인해 보겠습니다.

 

responseFields, fieldWithPath

이 메서드는 응답의 필드와 해당 필드명을 지정하는 건데 응답의 필드가 지정해준 것 이외에 필드가 있다면(혹은 없다면) test fail의 원인이 됩니다.

 

 

그런데 이러한 응답의 자세한 내부 필드까지 다 지정하기는 번거롭잖아요? 현재 응답 json객체는 contact와 contact2필드가 있는데 각각의 contact, contact2를 key로 가지는 value를 다 지정하지 않고 테스트하고 싶은데, 그럴때는 subsectionWithPath 를 사용합니다.

 

이렇게 지정하면 

subsection으로 지정한 contact와 contact2로 문서를 작성할 수 있습니다.

 

 

그런데 이번엔 또 항상 contact, contact2를 응답하는게 아니라 선택적으로 하나만 받는 상황에서는 test fail이 발생하잖아요? 그래서 relaxmode라는게 있습니다. (이 relaxmode는 다른 메서드에서도 계속 사용되므로 대표적으로 한 번만 보여드리겠습니다.)

 

이런식으로 relaxmode 메서드를 사용하게되면 응답의 필드가 contact.name 단 하나가 아니라 다른 것이 있더라도 test fail이 발생하지 않고 문서화를 진행합니다.

이런식으로 말입니다.

 

요청은 path variable이나 form data, header등 다양하게 문서활르 진행할 수 있는데

 

쿼리 스트링으로 넘겨 받은 api에 대한 테스트를 한 번 해 보겠습니다.

 

 

requestParameters, parameterWithName을 사용해서 문서화를 진행해 보겠습니다.

 

위 사진처럼 진행하게되면 

 

이와 같이 request parameter를 문서화할 수 있습니다. 

 

 

 

출처: https://docs.spring.io/spring-restdocs/docs/2.0.6.RELEASE/reference/html5/

Spring REST Docs

예제코드는 https://github.com/geneaky/BookChat

GitHub - geneaky/BookChat

위 레포에서 rest-doc브랜치에서 볼 수 있습니다.