Spring REST Docs

➡️Spring Rest Docs

프로젝트를 하다 보면 같이 프로젝트를 진행하는 팀원들에세 API문서를 제공할 일이 많다.그런데 직접API를 위키나 문서에 정리하게 되면 코드와 싱크를 맞추기가 힘들다.대부분 API코드가 변경되면 문서를 잘 변경하지 않는다.이러한 문제를 해결해 주는 게 Spring REST Dosc이다.

Spring REST Docs는 test code 기반으로 아래와 같이 문서를 생성해 준다.Test code 기반으로 문서가 생성되기 때문에 코드가 변경 되더라고 코드 기반으로 문서를 자동으로 업데이트하기 때문에 코드와 문서에 싱크 문제도 존재하지 않는다.

이러한 이유로 Rest docs는 API 문서로 사용하는데 아주 좋다.

Build gradle 설정 하기

1.Asciidoctor plugin

2.asciidoctor 구성에 spring-restdocs-asciidoctor 디펜던시를 추가한다. 이건 자동적으로 내 프로젝트에서 .adoc파일들을 읽어 build/generated-snippets에  파일을 읽어 HTML문서로 export한다.

 

3.Spring mvc rlqksdp  snippets을 뽑고싶다면 해당 의존성을 추가해주면 된다.

 

4.(ext) snippets의 생성될 위치를 지정해준다.

5.(test) 테스트 테스크가 실행될때 snippets들이 생성 위치에 떨어지게 설정해준다.

6.(asciidoctor) asciidoctor 테스크를 구성 해준다.

 

bootJar

7.문서가 만들어지기전에 test가 실행되도록 의존성을 걸어준다.

8.jar 생성전에 asciidoctor 테스크가 실행되도록 설정해준다.

9.jar static 폴더에 rest docs가 HTML로 생성되면 넣어준다.

 

Spring REST Docs Test code 작성

 

유저를 생성하는 컨트롤러 코드 

 

 

controller단위 테스트와 rest docs를 생성하도록 작성한 테스트 코드이다.

-setup 메소드는 Rest docs를 작성하기 위해 테스트 코드 실행 전 실행되는 메소드로 설정한다.

RestDocumentationContextPrevider 은 MVC rest docs 를 세팅할 때 사용한다.

그리고 아래처럼 테스트 코드 내부에 field문서를 작성해준다.

 

 

src/docs/asciidoc 에 파일명.adoc을 작성한다.

 

 

ADOC 작성

test를 실행하고 나면 build 폴더 안에 Generated-snippets에 문서가 작성된다.

이런식으로 편리하게 작성된다.