Spring REST Docs란?

Spring REST Docs란?

테스트 코드를 기반으로 자동으로 API문서를 자동으로 작성해주는 프레임워크

반드시 Test가 통과되어야 문서가 자동으로 작성되기 때문에 API Spec이 변경되거나 추가/삭제 되는 부분에 대해 항상 테스트 코드를 수정하여야 하며, API 문서가 최신화 될 수 있도록 해준다.

기본적으로 asciidoc을 사용하여 문서를 작성한다.

Spring REST Docs

Spring REST Docs Architecture

1. Test Case를 수행하면 산출물(adoc파일)이 /build/generate-snippets 디렉토리에 생성된다.
2. /src/docs/asciidoc 디렉토리에 Test Case 산출물(adoc파일)을 include하여 문서를 생성
   • /build/generate-snippets/*.adoc 파일들은 API Request, Response에 대한 Spec 파일
   • /src/docs/asciidoc/*.adoc 파일들이 html파일로 변환되어 API 문서로 제공된다.
   • /src/docs/asciidoc/*.adoc 에 API 문서를 작성하고,필요한 API Request, Response Spec은 자동 생성된 Test Case 산출물(adoc파일)을 이용해 표현
   • 이렇게 하면 향후 API Spec이 변경되더라도, 문서를 수정하지 않아도 되는 장점이 있다.
3. 이렇게 생성된 asciidoc 문서는 AsciidoctorTask를 통해 html 문서로 processing 되어 /build/asciidoc/html5 하위에 html문서로 생성
   • html 문서가 생성되는 기준은 /src/docs/asciidoc/*.adoc 파일을 기준으로 생성

Spring REST Docs 구축 예시