Rest docs 적용기

진행

기존 Swagger를 사용했었는데, REST docs 를 알게되어 한번 적용해보게 되었다.

왜 써야 할까

먼저 직접 생각해보자.

우선 문서 자체가 필요한 이유는

1. 프론트엔드에서 우리 API를 사용할 때
2. 혹시나 다른 백엔드 개발자가 추가적인 확장/수정 등을 할 때
3. API 설계에 대해 알아보기 쉽게 하기 위해
4. 더 쉬운 가독성을 위해
5. 변경되는 코드에 대해서 쉽게 적용하기 위해 (자동화를 할 경우에만 해당)

등 과 같은 이유로 사용을 한다.

Rest Docs 를 적용해보자.

1. 우선 먼저 build.gradle에 다음과 같이 설정을 해준다.

2. 이후 Rest Docs 를 적용할 API에 대해서 테스트 코드를 작성해준다.

: Rest Docs 는 각각의 API 기능에 대해서 테스트 코드가 없으면 적용이 되지 않는다. 따라서 각 API에 대해 테스트 코드를 작성해주자.

Rest docs를 위한 테스트 코드는 위와 같은 형식으로 작성하면 된다.

+> API의 parameter로 요청을 할 때, @RequestParam 인지, @PathVariable 인지 차이가 있다.
전자의 경우에 requestParameters, 후자의 경우 requestFields 를 통해서 테스트 코드를 작성해주었다.

3. 작성한 테스트코드들을 실행 후 성공한다면, 다음과 같은 파일들이 생성된다.

4. 이제 이 파일들을 이용해서 asciidocs를 통해서 문서를 생성해준다. asciidoc은 AsciiDoc 문법에 맞게 작성해주어야 한다.

생성된 html 파일에 들어가면 다음과 같이 문서가 생성된다.

Swagger ? Rest Docs ?

두 방법 모두 API 문서 자동화를 통해서 필요한 장점들을 모두 받을 수 있다. 서로 다른점을 찾자면, Swagger 는 UI를 통해서 좀 더 쉽게 다가갈 수 있다는 생각이 들었다. 또한 정상 작동여부는 보장해줄 순 없지만, 어느 정도 API를 Test 할 수 있다는 것이 장점인 것 같다.
그에 비해 Rest Docs는 이런 접근성에서는 우위를 점하지는 못하지만, 각각의 API에 대해 Test Code를 통해서 해당 기능이 정상작동 한다는 것을 보장할 수 있다는 것이 장점인 것 같다.

테스트 코드 작성에 도움이 되었던 에러

• 1
  

urlTemplate not found. If you are using MockMvc did you use RestDocumentationRequestBuilders to build the request?

배경 : rest docs 의 andDo document pathParameters 사용중, 이와 같은 오류 만남

해결 : pathParameter 사용 시 MockMvcBuilders 보다 RestDocumentationRequestBuilders를 이용하는 것이 좋다고 한다.