Spring Rest Docs 맛보기

API를 만들어주는 라이브러리 중 Spring RestDocs가 좋은점

• 운영중인 코드에 영향이 없음
• 테스트 케이스 실행했을 때 성공시 문서 생성해주므로 변경된 기능과 문서 동기화 가능(최신버전 유지 및 신뢰도 상승)
• 다만 버전에 따라 쓰는법이 조금 다르거나 버그가 있는 것 같다고 함

 

swagger에서 Spring Rest Docs를 바꿔보려고 한 이유

1. swagger는 테스트해보기엔 좋은데 API문서를 한눈에 보기 어려운 것 같다.

내부 테스트용으로는 좋을 것 같지만 깃 README에 올릴 문서가 필요했다.

 

2. 레디슨과 스웨거 버전 충돌이 있었음

이부분은 어찌저찌 해결했고,  Spring Rest Docs도 버전 탄다고 했지만 다른 방법을 시도할 명분이 되었다..

 

 

어떤 버전을 사용할까

GA버전 중 3.0.0은 최소 요구사항이 자바17이기 때문에 2.0.7을 사용했다.(나는 자바 11)

• SNAPSHOT : 아직 개발이 완료되지 않은 버전
• M(Milestone) : 개발은 완료되었으나, 아직 기능들을 개선하는 중 또는 버그를 수정하고 있는 버전
• GA(General Availability, General Acceptance) : 필요한 모든 상업화 활동이 완료되어 웹이나 물리 매체를 통해 시장에서 이용할 수 있음

 

 

적용방법 (Spring REST Docs 참고 )

1. dependency 추가

plugins { 
	id "org.asciidoctor.jvm.convert" version "3.3.2"
}

configurations {
	asciidoctorExt 
}

dependencies {
	asciidoctorExt 'org.springframework.restdocs:spring-restdocs-asciidoctor:{project-version}' 
	testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc:{project-version}' 
}

ext { 
	snippetsDir = file('build/generated-snippets')
}

test { 
	outputs.dir snippetsDir
}

asciidoctor { 
	inputs.dir snippetsDir 
	configurations 'asciidoctorExt' 
	dependsOn test 
}

 

2. junit5 테스트 코드 생성

- @SpringBootTest에 @ExtendWith(SpringExtension.class) 가 포함되어 있어 RestDocumentationExtension.class만 적음

import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.http.MediaType;
import org.springframework.restdocs.RestDocumentationContextProvider;
import org.springframework.restdocs.RestDocumentationExtension;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.setup.MockMvcBuilders;
import org.springframework.web.context.WebApplicationContext;

import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.documentationConfiguration;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultHandlers.print;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

@SpringBootTest
@ExtendWith(RestDocumentationExtension.class)
public class testController {

    private MockMvc mockMvc;

    @BeforeEach
    void setUp(WebApplicationContext webApplicationContext, RestDocumentationContextProvider restDocumentation) {
        this.mockMvc = MockMvcBuilders.webAppContextSetup(webApplicationContext)
                .apply(documentationConfiguration(restDocumentation))
                .build();
    }
    @Test
    void test1() throws Exception {
        this.mockMvc.perform(get("/").accept(MediaType.APPLICATION_JSON))
                .andExpect(status().isOk())
                .andDo(print())
                .andDo(document("index"));
    }
}

 

3. snippets가 생성되었음

4. 이제 이것을 html문서로 만들어주기 (Using the Sniffets)

  1) 소스파일의 경로로 파일을 생성

  2) 매크로 입력 (예시 : include::{snippets}/index/curl-request.adoc[])

  3) bootJar실행시 생성된 파일을 html형태로 만들어준다.

 

• 나는 Gradle이라 src/docs/asciidoc/index.adoc를 생성해주고 아래 내용을 입력하였다.

Build tool	Source files	Generated files
Maven	src/main/asciidoc/*.adoc	target/generated-docs/*.html
Gradle	src/docs/asciidoc/*.adoc	build/asciidoc/html5/*.html

 

(install AsciiDoc Plugin > 미리보기 가능해짐)

index.adoc

• gradle.yml의 bootJar 수정

bootJar {
   dependsOn asciidoctor

   copy {
      from asciidoctor.outputDir
      into "src/main/resources/static/docs"
   }
}

 

• 실행 > 아래의 경로로 파일이 복사된다. > 애플리케이션 실행후 확인 가능

 

---

정리

테스트 실행 -> 성공시 스니펫이 생성됨 -> 원하는 형태로 실행하는 매크로 파일을 거쳐 html파일이 생성됨 -> 애플리케이션 실행시 문서 확인 가능해짐

 

 

후기

Spring Rest Docs는 문서화와 테스트코드를 성공해야 한다는 점의 특징이 크게 와닿았다.

하지만 테스트 케이스 작성 안하면 생성이 되지 않기 때문에

개발자가 실수로 작성하지 않는다거나 테스트 실패하는 경우가 문제가 될 수도 있을 것 같다.

어쩌면 일이 많아질수도 있겠다는 생각이 들었다.

 

참고자료

소프트웨어 생명주기(버전)

호돌맨의 요절복통 개발쇼 

Spring REST Docs