Spring Rest Docs 소개 및 사용법

Spring Rest Docs 소개

Spring Rest Docs 공식 레퍼런스

Spring MVC test를 사용해서 문서의 일부분을 생성해낼 때 유용한 기능을 제공해주는 라이브러리이다.

우리가 만든 테스트를 실행할 때 사용하는 요청과 응답 및 응답에 실려나오는 header 이런 정보를 사용해서, 문서조각을 만들 수 있다. 이런 문서조각을 모아서 REST API Documentation을 완성할 수 있다(html로 만들어진다). Spring Rest Docs는 Asciidoctor 툴을 사용한다. plain text로 작성한 문서를 특별한 문법에 맞춰(mark down과 유사) page 문서로 만들어준다.

Rest Docs는 Test와 통합할 수 있는 방법

1. MockMvc
   • Spring Data REST
   • Spring HATEOAS
2. WebTestClient (Spring 5부터 지원)
   • WebTestClient
3. REST Assured
   • Grails
   • REST Assured
4. Advanced
   • Slate
   • TestNG
   • JUnit5

출처: Spring REST Docs

연동 방법 - MockMvc (Spring legacy 사용시)

private MockMvc mockMvc; 

@Autowired 
private WebApplicationContext context; 

@Before
public void setUp() {
    this.mockMvc = MockMvcBuilders.webAppContextSetup(this.context)
            .apply(DocumentationConfiguration(this.restDocumentation))
            .build();
}

위의 코드는 JUnit 4를 기준으로 작성된 것 JUnit 5를 사용하는 경우, 아래를 참조하여 작성

JUnit 4	JUnit 5
@BeforeClass	@BeforeAll
@Before	@BeforeEach
@After	@AfterEach
@AfterClass	@AfterAll

연동 방법 - MockMvc (SpringBoot 사용시)

애노테이션 하나만 추가하면 간편하게 설정할 수 있다.

테스트 위에 @AutoConfigureRestDocs를 추가하면 된다.

사용 방법 (연동 후)

this.mockMvc.perform(get("/").accept(MediaType.APPLICATION_JSON))
    .andExpect(status().isOk())
    .andDo(document("index", links(halLinks(), // (1)
        linkWithRel("alpha").description("Link to the alpha resource"), // (2)
        links(linkWithRel("bravo").description("Link to the bravo resource")))); // (3) 

설명

• (1): document라는 메서드를 사용해서 현재 이 테스트를 실행한 그 결과를 어떤 디렉토리, 어떤 이름으로 만들지 정해주는 것, "index" 문서 아래에 여러가지 snippets들이 만들어지게 된다.
• (2):

Swagger라는 자동화된 문서화 도구도 있지만 Rest Docs를 선호하는 이유 ?

우리가 API 코드를 변경했을 때, 테스트 코드 또한 변경할 것이다. 그때, 문서도 자동으로 같이 바뀐다. 테스트를 하지않은 내용 또한 추가로 생기면 그것 또한 문서화하도록 강제할 수 있다.

Swagger를 사용하는 것도 무관하지만 코드를 변경했는데(=API가 변경됐는데) 문서가 안바뀔 수도 있는 문제를 미연에 방지할 수 있기 떄문에 Spring Rest Docs를 선호한다.

snippets

• links()
• requestParameters() + parameterWithName()
• pathParameters() + parametersWithName()
• requestParts() + partWIthName()
• requestPartBody()
• requestPartFields()
• requestHeaders() + headerWithName()
• requestFields() + fieldWithPath()
• responseHeaders() + headerWithName()
• responseFields() + fieldWithPath()
• 이 외에도 다양한 정보들을 문서화할 수 있다.

Spring REST Docs 사용법

STEP 1. 의존성 추가하기 (프로젝트를 생성할 때, 이미 추가했다면 생략해도 무방)

STEP 2. Spring Rest Docs를 적용하고 싶다면, 만든 테스트 위에 @AutoConfigureRestDocs 추가한다

그러면 이제부터 REST Docs를 사용할 수 있는데..

STEP 3. REST Docs를 처음 사용하는 방법

.andDo(document(문서의 이름))

위와 같이 시작하면 된다.

ex)

위의 예제 테스트를 실행하면 아래와 같이 generated-snippets 이라는 폴더가 생겼고 그 안에 create-event가 생성된다. (원래는 target 폴더에 생성되는 것으로 예상했는데, 왜 난 build에 생기지...?)

그 결과 중 http-request를 봤을 때, 아래와 같이 포맷팅이 안되어 있어서 보기가 불편하다.

포맷팅을 하기위해서는 RestDocMockMvc 커스텀마이징이 필요하다.

커스텀마이징 방법은 test 패키지에....

1. RestDocsMockMvcConfigurationCustomizer를 구현한 빈 등록
2. @TestConfiguration // Test에서만 사용하는 Configuration이라고 알려주는 것

FunctionalInterface인 RestDocsMockMvcConfigurationCustomizer의 configurer만 재정의하면 된다. (예제에서는 request와 response를 이쁘게(prettyPrint()) 출력하도록 재정의한다.

RestDocsMockMvcConfigurationCustomizer 구현 예제

구현한 빈을 import 해준다!

그리고 실행한다

request value가 포맷팅되었다!

(prettyPrint는 Preprocessors 중 하나이다 공식 레퍼런스를 보면 이 외에도 다양한 프로세서가 있다)

참고자료: REST API 개발 - 백기선님 강의

참고하면 좋을 것 같은 자료: Spring REST Docs - Yun 블로그