Spring REST Docs에 대해 설명하고 어떻게 사용하는지에 대해 가볍게 기술합니다.

<aside> 💡 목차

</aside>

Spring REST Docs? 쓰는 이유

Spring REST Docs의 목적은 RESTful 서비스를 위한 정확하고 읽기 쉬운 문서를 작성하는 데 도움을 주는 것입니다. 고품질의 문서를 작성하고 유지하는 것은 어렵습니다.(문서 최신화는 더더욱 그렇습니다.) Spring REST Docs를 사용하면 프로그램 안에서 빌드를 통해 문서화 작업이 일어납니다. 설계에서 코드가 변경될 경우에는 코드를 수정하면 되기 때문에, 문서를 다른 곳에 관리할 경우와 비교하여 다시 문서를 최신화 하러 가는 거리가 더욱이 짧아집니다.

Asciodoctor란?

API 문서화를 위해 Spring REST Docs는 기본적으로 Asciodoctor를 사용합니다. Asciodoctor는 평문을 처리하고 사용자의 요구에 맞게 스타일화 및 배치된 HTML을 생성합니다. 원하는 경우 Spring REST Docs에서 Markdown을 사용하도록 구성할 수도 있습니다.

그래서 Spring REST Docs를 통해 API 문서가 만들어지면 *.adoc을 생성하여 확인할 수 있습니다.

(추가로 위와 같이 해당 파일을 바로 보기 위해서는, IDE에 플러그인을 추가하여오른쪽 화면과 같이 확인할 수 있습니다)