[Spring] Spring REST Docs를 이용한 API 문서화

Spring REST Docs 에 대한 설명

 

 

전체적인 흐름

빌드 -> 테스트 -> 스니펫 생성 -> asciidoctor에 의해 스니펫을 이용하여 html 생성(이때 반드시 src/docs/asciidoc 경로에 index.adoc 파일을 생성하여 어떻게 html 파일을 생성할 것인지 정의해줘야 한다. 여기서 adoc 파일의 파일명 그대로 html 파일이 생성된다.) -> build/docs/asciidoc 경로에 생성된 html 파일을 src/main/resources/static/docs 경로에 복사한다. -> src/main/resources/static 해당 경로는 정적 파일에 대한 루트 클래스패스로 docs/index.html 형식으로 요청하게 되면 API 문서화 페이지가 제공된다.

 

 

사용법 요약

1. build.gradle에 설정

2. 테스트 코드에 스니펫 생성 코드 추가

3. src/docs/asciidoc 경로에 원하는 파일명.adoc 파일 생성

4. build 실행

 

 

프로젝트에 적용하기

 

1. build.gradle에 관련 의존성 추가와 설정 적용하기

- plugins 블럭에 id "org.asciidoctor.jvm.convert" version "3.3.2" 추가하기

 

- spring-restdocs-mockmvc 라이브러리는 MockMvc를 사용하여 API 테스트에서 스니펫을 생성하는 역할을 한다.

- spring-restdocs-asciidoctor 라이브러리는 Asciidoctor를 사용하여 스니펫을 문서로 변환하는 역할을 한다.(Asciidoctor는 텍스트 기반 문서를 HTML, PDF 등 다양한 형식으로 변환하는데 사용되는 문서 변환 도구이다.)

 

- ext 블록은 Gradle 빌드 스크립트에서 사용자 정의 속성을 정의하는데 사용되는 확장 블록이다.

- snippetsDir 라는 확장 속성을 정의하고 있고 해당 속성은 build/generated-snippets 디렉토리를 가리키도록 설정되어 있다.

- 여기에서는 테스트에서 생성된 스니펫 파일이나 문서를 특정 디렉토리에 저장하기 위해서 사용한다.

 

- 사용자 정의 구성(의존성)을 설정하고 있다.

 

- test 작업시에 snippetsDir 변수를 출력 디렉토리로 지정한다.

 

- snippetsDir 디렉토리를 입력으로 지정하고 test 작업이 먼저 실행되도록 설정하고 있다.

 

- copyDocument 라는 사용자 정의 작업을 정의하였으며 해당 작업은 asciidoctor 작업 이후에 실행되며 Asciidoctor 작업의 출력 디렉토리의 파일을 src/main/resources/static/docs 디렉토리로 파일을 복사하는 작업을 한다.

 

- Spring Boot 애플리케이션을 패키징한 JAR 파일을 만들 때, 해당 JAR에 Asciidoctor로 생성된 문서를 포함시키도록 설정한다.

 

 

2. 테스트 코드에 적용하기

- 해당 컨트롤러 테스트 클래스 위에 붙여준다.

 

 

- post, patch, get, delete 메서드를 MockMvcRequestBuilders에서 RestDocumentationRequestBuilders로 변경해준다.

 

 

- 스니펫을 생성하는 코드를 위와 같이 추가해준다.

- 첫 파라미터인 identifier는 스니펫의 outDirs로 설정해둔 build/generated-snippets 경로에 생성되는 스니펫들의 디렉토리명이다.

 

 

- 응답이 list 형태라면 위와 같이 [].필드명 형태로 인자를 넣어줘야한다.

 

 

참고 자료

https://velog.io/@backtony/Spring-REST-Docs-%EC%A0%81%EC%9A%A9-%EB%B0%8F-%EC%B5%9C%EC%A0%81%ED%99%94-%ED%95%98%EA%B8%B0

Spring REST Docs 적용 및 최적화 하기