Spring REST DOCS를 Spring Boot에 적용하기 (1)

주요 REF

Spring REST DOCS DOCU
Asciidoctor

본 포스팅에선

1) Spring REST DOCS가 무엇인지
2) gradle + mockMvc 환경에서 Spring REST DOCS를 Spring BOOT에 어떻게 "기본" 적용하는지

다루고 있습니다!

Spring REST DOCS를 "활용"하는 방법은 여기를 참고해 주세요!

Spring REST DOCS란?

일단 Spring REST DOCS의 정의는 이렇다.

1) Spring MVC TEST에 의해 2) 자동 생성된 snippet과 3) 직접 작성한 문서를 결합하여 최종 Documentation을 만들어 주는 서비스

여기서 포인트는 3가지 이다.

1. Spring MVC TEST - snippet 만드는 방법은 Spring MVC TEST framework에 의존적이다. 즉, TEST framework 혹은 library가 달라지면 snippet 생성 방식이 조금씩 달라지게 된다.

2. 자동 생성된 snippet - 이때 snippet이 어디에 생성되고, 생성된 snippet 경로를 알 수 있는 방법은 build tool에 따라 다르다

3. 직접 작성한 문서 - 문서를 직접 작성하긴 해야 한다. 대신 snippet을 사용하므로 쉽고 간단한게 작성할 수 있다. 이때 "직접 작성한 문서"를 "html 파일로 변환"해 주는 것이 Ascii doctor이다.

snippet : REST API에 대한 정보를 담고 자동 생성되는 *.adoc 문서

본 문서에서는 gradle + MockMvc 환경에서 Spring REST DOCS를 Spring Boot에 적용하는 방법을 다룬다.

 

gradle 설정

새로운 라이브러리르 도입하는 것이므로, gradle에 몇 가지 설정해줄게 있다.

// 1. ascii doctor 플러그인 설정
plugins {
  id 'org.asciidoctor.convert' version "1.5.3"
}

// 2. asciidoctor Task 설정
asciidoctor {
    dependsOn test
}

// 3. bootJar Task 설정
bootJar {
    dependsOn asciidoctor
    from ("${asciidoctor.outputDir}/html5") {
        into "static/docs"
    }
}

// 4. mockMVC에 rest docs 추가하기
testImplementation('org.springframework.restdocs:spring-restdocs-mockmvc')

// 5. *.adoc 파일의 {snippets}를 자동으로 설정 - 아래에서 자세히 설명
asciidoctor 'org.springframework.restdocs:spring-restdocs-asciidoctor:2.0.3.RELEASE'

bootJar Task 설정에 대해 이야기를 살짝 해보자면, 생성된 jar 파일에 문서들을 static하게 넣고 싶을 때 사용하는 옵션이다.
war 파일을 생성하도록 했다면 bootWar Task를 넣어 주어야 한다.

 

snippet 생성을 위해 TEST 코드에 rest docs 코드 추가하기

@AutoConfigureRestDocs 어노테이션을 사용하면 rest docs 코드를 손쉽게 추가할 수 있게 설정해준다.

옵션으로는 스니펫이 생성될 위치, 스니펫에 보여질 URI 등이 있다.

아래는 코드 예시이다.

아주 간략/단순/간단하게 작성해보았다.

@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.MOCK)
@AutoConfigureRestDocs
public class XXXXTest {

  @Autowired
  private MockMvc mockMvc;

  @Test
  public void 무언가_테스트() {
    mockMvc.perform(get("/api/v1/data"))
      .andDo(print())
      .andExpect(status().isOk())
      .andDo(document("signup"))
  }

}

14번째 라인인 .andDo(document("signup"))이 핵심이다!

제일 간단한 스니펫 생성으로, 6가지 스니펫이 build/generated-snippets/signup에 생기게 된다.

6가지 스니펫 목록은 다음과 같다.

 

 

다른 스니펫을 만들거나 스니펫에 다양한 정보가 나오도록 하는 방법은 NOT-PREPARED에서 설명한다

 

documentation 작성

gradle은 /src/docs/asciidoc에 *.adoc 문서를 작성해야 한다.

adoc 문서의 문법은 여기에 잘 정리되어 있다.

간단하게 몇 가지만 살펴보면,

 

문서 제목은 문서의 첫 줄에 =를 붙이면 되고 =를 더 붙일수록 점점 내려간다 마치 마크다운의 #같은 느낌이다.

표는 아래와 같이 만들 수 있다.

 

[cols=2*,options=header]
|===
|Name
|Group

|Firefox
|Web Browser

|Ruby
|Programming Language

|===

 

 

스니펫을 가져오는 방법은

include::{snippets}/signup/curl-request.adoc[] 와 같이
include::{snippets}/그 다음 폴더/파일이름[]을 해주면 된다.

여기서 {snippets}가 의미하는 위치는 build/generated-snippets 이다.

간단하게 작성을 해보자

= 회원가입

== 회원가입 조회

include::{snippets}/signup/curl-request.adoc[]
include::{snippets}/signup/http-request.adoc[]
include::{snippets}/signup/http-response.adoc[]
include::{snippets}/signup/httpie-request.adoc[]

이렇게 되면 아까 해주었던 bootJar(bootWar) 설정에 의해 http://localhost:8080/docs/api-guide.html에서 확인할 수 있다.

 

build + run

IDE를 사용하고 있다면 run 옵션에 따라 http://localhost:8080/docs/api-guide.html를 찾지 못할 수도 있다.

테스트를 해서 build/ 내에 스니펫 파일들이 생성되어야 하기 때문이다.

따라서 안전하게 실행 시키기 위해서는

./gradlew build

java -jar ./build/libs/*.war

를 사용하는 것이 좋다!

 

 

틀렸거나 이해가 안되는 부분은 언제든지 댓글 남겨주세요!