[Spring] Spring REST Docs 상세 설정

개요

Spring REST Docs로 API 문서화를 적용하던 중 http-request와 response 형식을 마음대로 설정할 수 없을까 고민하였고, 알아낸 방법을 글로 정리해보았다.

 

---

적용

현재 프로젝트에서 인가가 필요한 API의 경우, access token을 Authorization header에 담아서 보내야 한다. MockMvc를 이용해 이런 API 요청을 문서화할 경우, 별도의 설정이 없다면 http-request.adoc에 access token이 그대로 보여지게 되는 문제가 발생한다.

 

이런 문제를 해결하기 위해서는 아래와 같이 별도의 설정을 추가해야 한다.

ResultActions response = mockMvc.perform(delete("/api/liked-vouchers/{voucherId}", voucherSaved.getId())
        .header("Authorization", tokenInfo.getGrantType() + " " + tokenInfo.getAccessToken()))
        .andDo(document("{class-name}/{method-name}",
                preprocessRequest(modifyHeaders().set("Authorization", "{ACCESS-TOKEN}"))) // 추가 
        );

위의 코드에서 HeadersModifyingOperationPreprocessor의 modifyHeaders().set("Authorization", "{ACCESS-TOKEN}"))는 문서화 적용 시, Authorization header를 {ACCESS-TOKEN} 이라는 문자로 변환해주는 역할을 한다. 이 설정을 추가하면 아래와 같이 문서화가 적용된다.

POST /api/liked-vouchers HTTP/1.1
Content-Type: application/json
Authorization: {ACCESS-TOKEN}
Content-Length: 1
Host: localhost:8080

7

해당 코드로 완성된 http-request.adoc을 자세히 확인해보면, Authorization header의 값이 {ACCESS-TOKEN}으로 적용된 것을 확인할 수 있다.

 

Header의 값을 변경하는 것 외에도, 원하지 않는 header를 보여주지 않도록 설정할 수 있다. 예를 들어, 위에서 나오는 Host header를 보여주지 않도록 설정하고 싶다면 아래와 같이 코드를 추가하면 된다.

ResultActions response = mockMvc.perform(delete("/api/liked-vouchers/{voucherId}", voucherSaved.getId())
        .header("Authorization", tokenInfo.getGrantType() + " " + tokenInfo.getAccessToken()))
        .andDo(document("{class-name}/{method-name}",
                preprocessRequest(
                        modifyHeaders()
                            	.set("Authorization", "{ACCESS-TOKEN}")
                                .remove("Host") // 추가
                ))
        );

modifyHeaders().remove("Host")는 Host라는 이름을 가진 header를 찾아 삭제하는 역할을 한다. 이 설정을 추가하면 아래와 같이 Host header가 문서에 없어진 것을 확인할 수 있다.

POST /api/liked-vouchers HTTP/1.1
Content-Type: application/json
Authorization: {ACCESS-TOKEN}
Content-Length: 1

7

 

해당 설정은 Request 뿐만 아니라, Response에도 적용이 가능하다. 문서화에 적용하고 싶지 않은 header가 있으면 이 방식으로 Response문서 또한 더 깔끔하게 작성할 수 있다.

 

---