[참고]
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 라는 플러그인 의존성을 주입하는 것부터 시작하면 된다.