본문 바로가기

웹 개발/Spring

[Spring] Spring Rest Docs

[참고]

Spring REST Docs Documentation (Spring REST Docs 공식 문서)

 

Spring REST Docs

Document RESTful services by combining hand-written documentation with auto-generated snippets produced with Spring MVC Test, WebTestClient, or REST Assured.

docs.spring.io

백기선님 강의 - 스프링 기반 REST API 개발 (섹션 3)

 

스프링 기반 REST API 개발 - 인프런 | 강의

다양한 스프링 기술을 사용하여 Self-Descriptive Message와 HATEOAS(Hypermedia as the engine of application state)를 만족하는 REST API를 개발하는 강의입니다., - 강의 소개 | 인프런...

www.inflearn.com

우아한 형제들 기술 블로그 - Spring REST Docs 적용

 

Spring Rest Docs 적용 | 우아한형제들 기술블로그

{{item.name}} 안녕하세요? 우아한형제들에서 정산시스템을 개발하고 있는 이호진입니다. 지금부터 정산시스템 API 문서를 wiki 에서 Spring Rest Docs 로 전환한 이야기를 해보려고 합니다. 1. 전환하는

techblog.woowahan.com

우아한 형제들 기술 블로그 - Spring REST Docs에 날개를… (feat: Popup)

 

Spring REST Docs에 날개를… (feat: Popup) | 우아한형제들 기술블로그

{{item.name}} 안녕하세요? 우아한형제들에서 정산시스템을 개발하고 있는 이호진입니다. 2018년 12월 Spring REST Docs를 주제로 사내 블로그를 작성 후… 1년 이상이 지났습니다. Spring REST Docs를 적용 후

techblog.woowahan.com

 

Spring Rest Docs의 장점(이자 단점)

테스트가 성공해야 API 문서를 만들 수 있다.

- ATDD(인수 테스트) 레벨의 테스트 코드 작성이 강제됨.

- 테스트 코드 기반으로 API 문서가 만들어지기 때문에 API 문서의 신뢰도가 높음

- API 문서 작성을 위해 프로덕션 코드에 추가되는 코드가 없음(예 : Swagger의 config 코드나 annotation 등) 

 

Spring Rest Docs와 함께 사용한 기술, 의존성

- 기술

- JUnit5

- assertj

- mockito

- asciidoctor

- ...

 

- 의존성

- spring-boot-starter-test

- spring-restdocs-mockmvc

- spring-security-test

- h2

- asciidoctor-maven-plugin

- maven-resources-plugin

- ...

 

흐름

테스트 코드 실행

pom.xml or build.gradle의 설정대로 스니펫 생성

asciidoctor 사이클 실행

html 문서 생성

생성된 문서 지정된 경로로 복사 (선택)

 

주의점

maven과 gradle의 디폴트 문서 생성 경로가 다름 (참고 : https://docs.spring.io/spring-restdocs/docs/current/reference/html5/#getting-started-using-the-snippets)

 

추가적으로 찾은 것

API 버전 관리 (/v1/**, /v2/**) 등을 탭별로 관리하고 싶다는 생각을 하고

Spring REST Docs 공식 문서에 아래와 같은 탭 형태의 문서가 많다는 것이 생각났다.

 

https://medium.com/@jason.moon.kr/using-tabs-in-asciidoc-spring-rest-docs-1fa8c092a3a

 

Using tabs in AsciiDoc (Spring REST Docs)

Spring REST Docs Reference를 보다 보면 아래와 같은 Tab 구성을 자주 만나게 된다.

medium.com

이 블로그를 참조하여 spring-asciidoctor-extensions 라는 플러그인 의존성을 주입하는 것부터 시작하면 된다.