01. Spring rest docs - 기본 설치 및 설정

특징

 

1. 테스트 코드 기반으로 문서를 작성함.

2. 테스트 코드에서 명세를 작성하기 때문에 비즈니스 로직의 가독성에 영향을 미치지 않는다.

 

maven dependecy, plugin 설정

 

<dependency> 
	<groupId>org.springframework.restdocs</groupId>
	<artifactId>spring-restdocs-mockmvc</artifactId>
	<version>{project-version}</version>
	<scope>test</scope>
</dependency>

<build>
	<plugins>
		<plugin> 
			<groupId>org.asciidoctor</groupId>
			<artifactId>asciidoctor-maven-plugin</artifactId>
			<version>1.5.8</version>
			<executions>
				<execution>
					<id>generate-docs</id>
					<phase>prepare-package</phase> 
					<goals>
						<goal>process-asciidoc</goal>
					</goals>
					<configuration>
						<backend>html</backend>
						<doctype>book</doctype>
					</configuration>
				</execution>
			</executions>
			<dependencies>
				<dependency> 
					<groupId>org.springframework.restdocs</groupId>
					<artifactId>spring-restdocs-asciidoctor</artifactId>
					<version>{project-version}</version>
				</dependency>
			</dependencies>
		</plugin>
	</plugins>
</build>

작성된 doc을 jar에 package하기 위해 플러그인 추가

<plugin> 
	<artifactId>maven-resources-plugin</artifactId>
	<version>2.7</version>
	<executions>
		<execution>
			<id>copy-resources</id>
			<phase>prepare-package</phase>
			<goals>
				<goal>copy-resources</goal>
			</goals>
			<configuration> 
				<outputDirectory>
					${project.build.outputDirectory}/static/docs
				</outputDirectory>
				<resources>
					<resource>
						<directory>
							${project.build.directory}/generated-docs
						</directory>
					</resource>
				</resources>
			</configuration>
		</execution>
	</executions>
</plugin>

 

설정 후 테스트 클래스 및 테스트 api 생성

 

@RestController
@RequestMapping("/mainApi")
public class MainApiController {
	
	@GetMapping("/test")
    public Map<String, String> getTest() {
        return Collections.singletonMap("code", "ok");
    }
}

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.MockMvcResultMatchers.status;

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;

@ExtendWith(RestDocumentationExtension.class)
@SpringBootTest
public class JUnit5ExampleTests {
    private MockMvc mockMvc;
    
    @BeforeEach
    public void setUp(WebApplicationContext webApplicationContext,
            RestDocumentationContextProvider restDocumentation) {
        this.mockMvc = MockMvcBuilders.webAppContextSetup(webApplicationContext)
                .apply(documentationConfiguration(restDocumentation)) 
                .build();
    }
    
    @Test
    public void getTestTest() throws Exception {
        this.mockMvc.perform(get("/mainApi/test").accept(MediaType.APPLICATION_JSON))
                .andExpect(status().isOk())
                .andDo(document("get-test"));
    }
}

 

테스트 성공하면 mvn clean install 실행함.

 

 

pom.xml에서 설정한 것 처럼 target 밑에 *.adoc 파일들이 생성된다.

 

main 밑에 asciidoc 폴더 생성 후 *.adoc 파일을 생성해준다.

 

 

해당 파일에 다음과 같이 간단히 작성하고 테스트 해보자.

상세 레퍼런스는 다음을 참고.

(https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/)

AsciiDoc - AsciiDoc Syntax Quick Reference

 

= 테스트문서
:toc: left

== 테스트API
.Http Request
include::{snippets}/get-test/http-request.adoc[]

.Http Response
include::{snippets}/get-test/http-response.adoc[]

 

그후 mvn install을 진행하면 target -> generated-docs 밑에 html 파일이 생긴다.

 

html을 열어보면 테스트문서가 뜬며 기본 설정이 완료된다.