Spring Rest Docs 와 Swagger 그리고 적용

Spring Rest Docs과 Swagger란?

Restful API를 사용하기 위해선 문서화가 굉장히 중요하다. 그렇기 때문에 자동화를 도와줄 툴이 필요한데 대표적으로 쓰이는 이 두개를 비교하여 선택하기 위한 게시글 입니다.

 

	Spring Rest Docs	Swagger
장점	제품코드에 영향이 없다	API를 테스트 해 볼수 있는 화면을 제공한다.
	테스트가 성공해야 문서작성된다.	적용하기 쉽다
단점	적용하기 어렵다	제품코드에 어노테이션 추가해야한다.
		제품코드와 동기화가 안될 수 있다.

API 문서의 목적은 개발하는 스펙을 정의하는 것이라 생각한다. Swagger는 API 동작을 테스트하는 용도에 더 특화되어 있습니다. 반면에 Spring Rest Docs는 깔끔 명료한 문서를 만들 수 있습니다.

그래서 문서 제공용으로는 Spring Rest Docs가 좀더 나을 수 있습니다.

Junit vs Spock

	Junit	Spock
장점	라이브러리를 추가하지 않아도 된다.	BDD 스타일로 직관적이다.
	컴파일 시점에 오류를 잡기 쉽다.	동적 테스트가 쉽다.
단점	동적 테스트 작성이 불편하다.	라이브러리를 추가해야한다.
		컴파일 시점에 오류를 찾기가 어렵다.

Spock은 별도의 라이브러리를 추가해야하고 문서작성용으로는 조금 과할수도 있기에 Junit이 좀더 낫다고 판다.

MockMvc(@WebMvcTest) vs Rest Assured(@SpringBootTest)

보통 문서를 작성할 때 서비스 계층은 Mocking을 하여 작성합니다. Rest Assured는 BDD 스타일로 직관적이지만 별도의 구성없이는 @SpringBootTest로 수행해야합니다. 그러면 전체 컨테스트를 로드하여 빈을 주입하기에 속도가 많이 느립니다. 반면에 MockMvc는 @WebMvcTest로 수행이 가능합니다. 그래서 Controller Layer만 테스트 하기에 속도가 빠릅니다. 만약 통합테스트를 한다면 Rest Assured가 좋은 선택일것 같지만 Spring Rest Docs로 문서를 작성하는데에는 MockMvc가 더 나은 선택이라 생각됩니다.

AsciiDoc vs Markdown

마크다운이 작성하기는 더 편하지만 Include가 되지 않는 단점이 있습니다. Slate를 사용하면 가능하다고 하지만 결과물이 우리가 생각한 doc파일과는 다르며 별도 설정을 해야하는 번거로움이 있습니다. 그래서 AsciiDoc가 낫다고 판단.

 

Rest Docs는 기본적으로 Asciidoc을 사용하며 작성된 테스트 코드에 의해 html파일을 생성해줍니다. 자동생성된 스니펫과 자신이 원하는 문서를 결합해서 사용할 수 있습니다.

Rest Docs 적용해보기

1. Spring TEST에 의해 성공한 케이스들에 대한 snippet이 자동으로 생성된다.

2. 문서를 직접 작성하고 코드들에 대한 정보는 아까 생성된 snippet을 include하여 추가하여 완성한다.

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번 5번은 디펜던시 안에 넣으면 된다.
// 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 코드를 손쉽게 추가할 수 있게 해준다.

@Test
    public void list() throws Exception {
        List<Restaurant> restaurants = new ArrayList<>();
        restaurants.add(Restaurant.builder()
                .id(1004L)
                .name("JOKER House")
                .address("Seoul")
                .build());
        given(restaurantService.getRestaurants()).willReturn(restaurants);

        mvc.perform(get("/restaurants"))
                .andDo(print())
                .andExpect(status().isOk())
                .andDo(document("list-api"))
                .andExpect(content().string(containsString("\"id\":1004")))
                .andExpect(content().string(containsString("\"name\":\"JOKER House\"")));
    }

위와 같이 mvc.perform 하위에 get아래 andDo(print())를 삽입해주고 isOk아래에 andDo(document(""))을 삽입해주면 되는데 "" 이 빈칸은 스니펫 생성시 만들어질 폴더의 이름이다. 이 상태로 테스트를 실행했을 때 성공을 하게 되면 build/generated-snippets 아래에 .adoc 파일이 기본적으로 6개가 생성될 것이다.

화면에 보여줄 문서 만들기

이제 스니펫을 추가하여 사용자들에게 보여줄 문서를 만들어야 할 차례다.

src/docs/asciidoc/api-docs.adoc 라는 파일을 생성하자.

자세한 작성법은 asciidoc를 찾아서 작성해야할 것이며 가장 기본적으로 마크다운에서 #이 =와 대칭이 되는것 같다.

 

작성예시)

= 밥집

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

 

gradle build하기

이제 gradle을 run 시켜서 완성된 html 파일을 만들어야하는데 보통은 ./gradlew build 같은 터미널 실행을 하면 되지만 필자의 경우엔 해당 명령어가 안먹어서 오른쪽 끝에 그래들을 열어서 직접 실행시켜줬다.

그러면 build/asciidoc/html 하위에 완성된 html이 만들어진다.

 

필자는 eatgo-api라는 상위 디렉터리를 만들어서 그 안에 생성하였다.

 

 

출처

https://lannstark.tistory.com/9

http://woowabros.github.io/experience/2018/12/28/spring-rest-docs.html