treecode

 이전에 Swagger로 API 문서를 만들어봤는데 UI도 예쁘게 만들어주고 API 테스트도 해볼 수 있어서 편리하게 사용했었다.

하지만 컨트롤러에 설정 코드가 많이 들어가고 동기화가 되지 않는 단점이 있어서 이번에는 Spring Rest Docs를 공부해서 적용을 해보았다.

Asciidoctor로 만든 문서와 Spring MVC Test로 생성된 AsciiDoc 스니펫을 결합하여 API 문서(HTML)를 만든다고 나와있는데 원하는 경우 Markdown을 사용하도록 Spring REST Docs를 구성할 수도 있다고 한다.

1. 설정

Asciidoctor Plugin

*.adoc으로 생성된 asciidoc 파일을 html로 변환해주는 플러그인, 처음에 "org.asciidoctor.convert" 를 사용했다가 오류가 떠서 확인해보니 Gradle 7 부터는 "org.asciidoctor.jvm.convert"를 사용한다고 한다.

그리고 asciidoctorExtensions 설정도 추가해준다.

snippetsDir에 테스트 빌드로 생성되는(outputs) 스니펫들이 저장될 위치를 지정해준다.

dependsOn은 해당 작업에 의존한다는 의미로 bootJar를 실행하면 asciidoctor가 먼저 실행이 된다. 그리고 finalizedBy는 후행 작업을 명시하는 것으로 마지막에 build/docs/asciidoc/ 에 생성된 html 파일을 static 경로에 복사한다.

블로그 보면서 해보다가 설정 안 맞아서 고생했는데 블로그 글을 쓰면서 공식 문서를 살펴보니 다시 한번 공식 문서의 중요성을 느끼게 된다.

2. 테스트 코드

@AutoConfigureRestDocs 애노테이션으로 Rest Docs 여러 설정을 간편하게 할 수 있다.

우선 순위에 따라 @AutoConfigureRestDocs(), OperationRequestPreprocessor로 url 설정을 할 수 있다.

MockMvc, Rest Assured 등으로 테스트를 작성하면 되는데 API 명세를 ResourceSnippetParameters builder()로 만든다,

3. 결과

퀄리티는 만들기 나름이라고 하는데.. Swagger를 썼을 때의 UI에 비하면 아주 심심한 화면이다. 그래서 더 괜찮은 방법이 없나 찾아보다가 Rest Docs랑 Swagger UI를 결합하는 방식을 소개하는 글을 발견해서 결국 해당 방식으로 변경을 했다!

이거에 대한 정리는 다음에 이어서 해야겠다.

[참고]