Spring Rest Docs

Spring Rest Docs란?

REST 프로젝트를 정확하고 가독성 높게 문서화하는 API입니다.

Spring MVC Test와 함께 자동 생성된 snippet들과 손으로 쓴 Asciidoctor 형식 문서를 결합해줍니다.

이러한 접근은 당신에게 Swagger같은 툴로 만들어진 문서들의 한계를 벗어나게 해줍니다.

 

그러니까 강력한 문서화  템플릿을 제공합니다.

 

소개

질 좋은 문서를 만드는 건 어렵습니다. 특화된 툴을 사용하면 쉽습니다. 

그게 바로 Spring Rest Docs

Spring Rest Docs는 기본적으로 Asciidoctor를 사용합니다.

Asciidoctor는 순수한 텍스트를 훑으며 당신의 필요에 딱 맞는 스타일과 레이아웃의  HTML을 제공합니다. 

Spring Rest Docs가 Markdown을 쓰도록 수정할 수도 있습니다.

 

Spring Rest Docs는 Spring MVC 테스트가 생성하는 snippet을 사용합니다.

TDD적인 접근은 서비스 문서의 정확도를 보장합니다.

스니펫이 부정확하다면 그 스니펫이 생성하는 테스트는 실패합니다.

 

REST 서비스 문서화는 그것의 resource를 설명하는 것에 많은 것이 달려있습니다.

각 resource 설명의 두가지 주요한 부분이 있습니다.

첫째는 리소스에서 사용하는 HTTP 요청의 세부정보이고,

둘째는 리소스에서 생성하는 HTTP 응답의 세부 정보입니다.

 

Spring REST Docs는 문서가 불필요한 세부정보를 포함하는걸 방지하며

이 리소스들 그리고 HTTP 요청과 응답들을 다룰 수 있도록 해줍니다.

이러한 분리는 서비스 API의 문서화를 돕습니다. 구현 말고요.

그리고 문서를 다시 고치지 않고도 구현을 발전시킬 수 있게 합니다.

 

Spring Rest Docs 사용법

docs.spring.io/spring-restdocs/docs/2.0.5.RELEASE/reference/html5/

자세한 것은 위 문서를 참고하세요

 

빌드 설정

Spring REST Docs를 사용하기 위한 첫번째 단계는 프로젝트 빌드 설정을 바꾸는 것입니다.

 

문서 패키징

스니펫 문서 실행시키기

테스트 설정하기