Spring REST Docs 를 사용해 문서 자동화하는 방법 + 샘플 프로젝트 작성 (Spring +JPA)

 

* 혹시나 바로 코드부터 보고 싶은 사람들은 
-> " Spring REST Docs 를 이용한 Sample Project " 검색 레쭈고 

 

 

 

0️⃣ Spring REST Docs 란 ? 

: Spring MVC Test 또는 WebTestClient으로 생성된 스니펫과 직접 작성한 문서를 결합하여 Restful 서비스를 문서화하는 것이다. 

 

https://docs.spring.io/spring-restdocs/docs/current/reference/htmlsingle/#introduction

Spring REST Docs

-> Spring REST Docs 관련 공식 문서이다. 설명이 잘 되어 있어서 사실 여기에 나온대로 따라서 하면 문서를 만들 수 있다. 

 

 

Spring REST Docs는 기본적으로 Asciidoctor를 사용한다. Asciidoctor는 일반 텍스트를 처리하고 필요에 맞게 스타일과 레이아웃을 갖춘 HTML 을 생성해준다. (여기서는 스니펫을 모아 결합한 것을 HTML 로 변환해준다.)

Spring REST Docs 는 Spring MVC의 테스트 프레임 워크, Spring WebTestClient 또는 REST Assured 5로 작성된 테스트에서 생성된 스니펫을 사용한다.

이 테스트 기반 접근 방식은 서비스 문서의 정확성을 보장하는데 도움이 된다. -> 신뢰성 !! 왜냐하면 테스트에 실패하는 케이스가 있다면 문서를 만들 수 없다. 

 

Swagger 대신 Spring REST Docs 를 사용한 이유 ? 

사실 둘 중  뭐가 더 낫다 ! 라고 말은 할 수 없다. 둘 다 장단점이 있기 때문이다. 

- Swagger는 적용이 쉽고, 문서에서 바로 호출해 테스트해볼 수 있다는 장점이 있지만, 프로덕션 코드에 침투적이며 테스트와는 무관해서 신뢰성은 떨어진다는 단점이 있다. 

- Spring REST Docs 는 Swagger와 다르게 테스트를 통과해야 문서가 만들어지기 때문에 신뢰도가 높고, 프로덕션 코드와 분리해서 테스트 코드에서 문서를 작성하기 때문에 침투적이지 않다. 하지만 Swagger에 비하면 훨씬 코드양이 많고, 설정이 어렵다는 단점이 있다. 

=> 우선 처음에 나는 Swagger를 통해 작성하면 사실 코드는 간편하니까 좋다고 생각했다.
근데 문서 커스텀을 위해서는 점점 메인 코드들에 불필요한 어노테이션들이 들어가니까 코드가 지저분해 지는게 싫었다. 그리고 api 문서를 만들고 싶은것이므로 Spring REST Docs가 더 낫다는 생각으로 바뀌었다. 
굳이 직접 호출해 테스트 하는 것은 인텔리제이에서 사용 가능한 httpd 를 활용하면 된다고 생각한다. (클라이언트 입장은 아니지만) 

그리고 우리 회사 기준? 이기는 하지만 api 문서를 v0.1 이런식으로 만드는데 수정하고 파일을 공유해도 어떤 사람은 아직도 0.1 버전보고 있고, 어떤 사람은 0.2 버전을 보고 있고,,? 최신 문서를 보지 않는 경우가 있는 것 같았다. 
바빠서 메일 확인을 바로바로 못하면 그럴 수 있다고 생각한다. 그래서 이럴거면 코드 수정 후 항상 테스트 하고 성공하면 api 문서도 만들어지니까 이렇게 확인하는게 더 낫다고 생각했다. 

사실 설정이야 처음에만 어렵다고 생각한다. 그리고 Asciidoc 문법이 어렵다고 느껴질 수 있다. 근데 이건 사실 처음 해봐서 그런거 아닐까? 라는 생각... 익숙해지면 이게 더 낫다고 생각한다. 
처음에는 물론 시간도 오래 걸리고, 코드 양도 많아서 귀찮아질 수 있지만, word로 표그리고, 거기에 설명 쓰고 하는 것보다 이게 훨씬 좋다고 생각한다. (이건 내가 워드 작업을 별로 안좋아해서 일수도...) 
암튼 이런 저런 이유로 나는 Spring REST Docs를 선택했다. 

 

 

1️⃣ Spring REST Docs 시작하기 + 설정 

샘플 프로젝트를 통해서 설정하는 방법, 문서 만드는 방법들을 간단하게 알아볼 예정이다. 

 

최소 요구사항 
- 자바 17 
- 스프링 프레임워크 6 

 

샘플 프로젝트 환경 
- 자바 17 
- 스프링 부트 3.2.2 
- JPA + H2
- Junit5  + MockMVC 
- AsciiDoc

 

 

build.gradle 

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

configurations {
	asciidoctorExt (2)
}

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

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

test { (6)
	outputs.dir snippetsDir
}

asciidoctor { (7)
	inputs.dir snippetsDir (8)
	configurations 'asciidoctorExt' (9)
	dependsOn test (10)
}

 

-> 공식 문서에 나와있는 build.gradle 설정 방식이다. 

 

(1) AsciiDoc 파일을 컨버팅하고 Build 폴더에 복사하기 위한 플러그인이다.

(2) Asciidoctor 를 확장하는 종속성에 대한 구성을 선언한다.

(3) asciidoctorExt 구성에 spring-restdocs-asciidoctor에 대한 종속성을 추가한다. 그러면 .adoc 파일에서 사용할 snippets 속성이 build/generated-snippets를 가리키도록 자동으로 구성된다. 또한 작업 블록 매크로를 사용할 수도 있다.

(4) mockmvc를 restdocs에 사용할 수 있게 하는 라이브러리 → 만약 Rest Assured 를 사용하고자 한다면 다른 라이브러리 사용해야함

(5) 생성된 코드 조각의 출력 위치를 정의하는 snippetsDir 속성

(6) Gradle 이 테스트 작업을 실행하면 출력이 snippetsDir에 기록된다.

(7) asciidoctor task를 구성한다.

(8) 작업을 실행하면 snippetsDir에서 읽는다.

(9) 확장을 위해 asciidoctorExt 을 구성한다.

(10) 테스트가 먼저 실행되고 문서가 생성되도록 한다.

(11) gradle build 시 asciidoctor 먼저 수행 후, bootJar 가 수행된다.

(12) gradle build 시 build/generated-snippets/html5에 html 파일이 생기고, gradle build 시 static/docs 폴더에 복사된다.

 

순서 : test -> asciidoctor -> bootJar 

 

 

테스트 설정 

: Spring REST Dcos는 Junit5 및 Junit4를 지원하고, Junit5 사용을 권장한다. 

@ExtendWith(RestDocumentationExtension.class) // (1) 
public class JUnit5ExampleTests {
		private MockMvc mockMvc;
		
		@BeforeEach // (2) 
		void setUp(WebApplicationContext webApplicationContext, RestDocumentationContextProvider restDocumentation) {
			this.mockMvc = MockMvcBuilders.webAppContextSetup(webApplicationContext)
				.apply(documentationConfiguration(restDocumentation)) 
				.build();
		}
	}

 

(1) RestDocumentationExtension 테스트 클래스 적용

(2) MockMvc 구성하기 위해 @BeforeEach 메서드를 제공해야 한다.

 

-> 사실 이렇게 두개만 설정해주면 기본 설정은 다 한 것이고, 이제 문서를 만들기 위한 코드를 작성해주면 된다. 

 

 

2️⃣ Restful 서비스 호출 , 요청 및 응답 문서화 

 

Restful 서비스 호출

this.mockMvc.perform(get("/").accept(MediaType.APPLICATION_JSON)) // (1) 
	.andExpect(status().isOk()) // (2) 
	.andDo(document("index")); // (3) 

(1) get 요청으로 서비스의 루트를 호출한다.

(2) 서비스가 예상하는 응답을 생성했는지 확인한다.

(3) 서비스에 대한 호출을 문서화하여 “index” 라는 디렉터리에 코드 조각을 작성한다. 스니펫은 RestDocumentationResultHandler에 의해서 작성된다.

 

그리고 기본적으로 6개의 스니펫이 생긴다.

• <output-directory>/index/curl-request.adoc
• <output-directory>/index/http-request.adoc
• <output-directory>/index/http-response.adoc
• <output-directory>/index/httpie-request.adoc
• <output-directory>/index/request-body.adoc
• <output-directory>/index/response-body.adoc

 

스니펫 사용

생성된 스니펫을 사용하기 전에 소스 파일을 생성 해야 한다. 그래들은 src/docs/asciidoc/(파일명).doc 으로 소스파일을 생성하면 된다.

생성 후,

include::{snippets}/index/curl-request.adoc[]

→ 이런식으로 include를 사용하여 수동으로 생성된 Asciidoc 파일에 생성된 조각을 포함할 수 있다.

 

 

 API 문서화

• 요청 및 응답 필드

{
	"contact": {
		"name": "Jane Doe",
		"email": "jane.doe@example.com"
	}
}

this.mockMvc.perform(get("/user/5").accept(MediaType.APPLICATION_JSON))
	.andExpect(status().isOk())
	.andDo(document("index", responseFields( // (1) 
			fieldWithPath("contact.email").description("The user's email address"), // (2)
			fieldWithPath("contact.name").description("The user's name"))));

(1) org.springframework.restdocs.payload.PayloadDocumentation의 정적 메소드로 응답 페이로드의 필드를 설명하는 조각을 생성하는 코드 → 요청을 문서화 하려면 requestFields를 사용하면 된다.

(2) path가 있는 필드를 사용하면 된다.

→ 위에 코드의 결과로는 응답 필드를 설명하는 테이블이 포함된 스니펫으로, 응답이므로 response-fields.adoc으로 생성된다.

(이때 문서화되지 않은 필드들이 존재할 경우 테스트 실패하는데 모든 필드를 문서로 제공하고 싶지 않을 때는 페이로드의 전체 하위 섹션을 문서화할 수도 있다.)

 

• 쿼리 매개변수

this.mockMvc.perform(get("/users?page=2&per_page=100")) 
	.andExpect(status().isOk())
	.andDo(document("users", queryParameters( // (1)
			parameterWithName("page").description("The page to retrieve"), // (2)
			parameterWithName("per_page").description("Entries per page")
	)));

(1) 요청의 쿼리 매개변수를 설명하는 조각을 생성하도록 Spring REST Docs 를 구성한다. org.springframework.restdocs.request.RequestDocumentation. 의 queryParameters의 정적 메서드를 사용한다.

(2) 매개변수들을 문서화 할 때는 parameterWithName를 사용한다.

 

• 경로 매개변수

this.mockMvc.perform(get("/locations/{latitude}/{longitude}", 51.5072, 0.1275)) 
	.andExpect(status().isOk())
	.andDo(document("locations", pathParameters( // (1) 
			parameterWithName("latitude").description("The location's latitude"),  // (2)
			parameterWithName("longitude").description("The location's longitude") 
	)));

(1) 요청의 경로 매개변수를 설명하는 조각을 생성하도록 Spring REST Docs 를 구성한다. 이때 org.springframework.restdocs.request.RequestDocumentation.의 pathParameters 정적 메서드를 사용한다.

(2) 매개변수를 문서화할 때는org.springframework.restdocs.request.RequestDocumentation.의 parameterWithName 에서 정적 메서드를 사용한다.

→ 위에 코드의 결과로는 path parameters 필드를 설명하는 테이블이 포함된 스니펫으로, 응답이므로 path-parameters.adoc으로 생성된다.

(이때 문서화되지 않은 쿼리 파라미터들이 존재하면 테스트 실패하는데, 만약 쿼리 매개변수를 문서화하지 않으려면 해당 매개변수를 무시됨으로 표시할 수 있다. )

 

* 대표적인 기능들만 정의한 것으로, 더 자세한 기능은

https://docs.spring.io/spring-restdocs/docs/current/reference/htmlsingle/#introduction

→ Spring REST Docs 공식 문서 참조

 

 

3️⃣  Spring REST Docs 를 이용한 Sample Project 

 

build.gradle 

plugins {
	id 'java'
	id 'org.springframework.boot' version '3.2.2'
	id 'io.spring.dependency-management' version '1.1.4'

	id "org.asciidoctor.jvm.convert" version "3.3.2" // Asciidoctor plugin 을 적용해야 함 (sciiDoc 문법으로 작성하면 Asciidoctor를 이용해서 html로 변환해준다.)
}

group = 'com.sample'
version = '0.0.1-SNAPSHOT'

java {
	sourceCompatibility = '17'
}

configurations {
	asciidoctorExt // Asciidoctor 를 확장하는 종속성에 대한 구성을 선언
}

repositories {
	mavenCentral()
}

dependencies {
	implementation 'org.springframework.boot:spring-boot-starter'
	implementation 'org.springframework.boot:spring-boot-starter-web'
	implementation 'org.springframework.boot:spring-boot-starter-data-jpa'

	compileOnly 'org.projectlombok:lombok'
	runtimeOnly 'com.h2database:h2'
	annotationProcessor 'org.projectlombok:lombok'

	// RestDocs
	asciidoctorExt 'org.springframework.restdocs:spring-restdocs-asciidoctor'
	testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'

	testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

tasks.named('test') {
	useJUnitPlatform()
}


ext {
	// snippetsDir 생성된 조각(snipppets)의 출력 위치를 정의하는 속성을 구성
	snippetsDir = file('build/generated-snippets')
}

test {
	// test 작업을 실행하면 출력이 snippetsDir에 기록된다는 점을 Gradle이 인식하도록 한다.
	outputs.dir snippetsDir
}

asciidoctor { // asciidoctor 작업을 구성
	inputs.dir snippetsDir // 7. 작업을 실행하면 snippetDir에서 입력을 읽게된다고 Gradle에 인식
	configurations 'asciidoctorExt'
	dependsOn test //  test 수행한 다음에 asciidoctor를 수행한다.
}

bootJar {
	dependsOn asciidoctor // test -> asciidoctor -> bootJar
	copy {
		from asciidoctor.outputDir
		into 'src/main/resources/static/docs'
	}
}

 

+spring.profiles.active = real (실서버) 일 경우에 Spring REST Docs 문서 생성 못하도록 막는 방법

bootJar {
	dependsOn asciidoctor // test -> asciidoctor -> bootJar

	String activeProfile = System.properties['spring.profiles.active']
	if(activeProfile != "real") {
		copy {
			from asciidoctor.outputDir
			into 'src/main/resources/static/docs'
		}
	}
}

-> 실제 운영 환경에서 api 문서가 생성되면 안되기 때문에 bootJar 실행할 때 이렇게 막아두면 문서 복사를 안한다! 

 

 

*문서작성을 위한 샘플 프로젝트 코드 (프로덕션 코드) 

: 그냥 테스트 코드만 보여줄까.. 하다가..뭐 코드가 많은 것도 아니니..  그냥 코드 다 공개합니다! (참고하세유) 

 

Post

package com.sample.restDocs.vo;

import jakarta.persistence.Entity;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.GenerationType;
import jakarta.persistence.Id;
import lombok.Builder;
import lombok.Getter;
import lombok.NoArgsConstructor;

@Getter
@Entity
@NoArgsConstructor
public class Post
{
	@Id
	@GeneratedValue(strategy = GenerationType.IDENTITY)
	private Long id;
	
	private String title;
	private String content;
	
	@Builder
	public Post(Long id, String title, String content)
	{
		this.id = id;
		this.title = title;
		this.content = content;
	}
	
	public void change(String title, String content)
	{
		this.title = title;
		this.content = content;
	}
}

-> 간단하게 제목, 내용 작성만 할 수 있게 했다. 

 

 

PostController 

package com.sample.restDocs.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import com.sample.restDocs.controller.request.PostCreateRequest;
import com.sample.restDocs.controller.request.PostEditRequest;
import com.sample.restDocs.controller.response.ApiResponse;
import com.sample.restDocs.service.response.PostResponse;
import com.sample.restDocs.service.PostService;

import lombok.RequiredArgsConstructor;

@RequestMapping("/api/v1")
@RequiredArgsConstructor
@RestController
public class PostController
{
	private final PostService postService;
	
	/**
	 * 글 작성
	 * @param request
	 * @return
	 */
	@PostMapping("/post")
	public ApiResponse<PostResponse> writePost(@RequestBody PostCreateRequest request)
	{
		return ApiResponse.ok(postService.writePost(request));
	}
	
	/**
	 * 글 단건 조회
	 * @param postId
	 * @return
	 */
	@GetMapping("/post/{postId}")
	public ApiResponse<PostResponse> getPost(@PathVariable(value = "postId") Long postId)
	{
		return ApiResponse.ok(postService.getPost(postId));
	}
	
	/**
	 * 글 수정
	 * @param postId
	 * @param request
	 * @return
	 */
	@PostMapping("/post/{postId}")
	public ApiResponse<PostResponse> updatePost(@PathVariable(value = "postId")Long postId, @RequestBody PostEditRequest request)
	{
		return ApiResponse.ok(postService.editPost(postId, request));
	}
	
}

-> 샘플 프로젝트로 만들 건 간단하게 글 작성 및 수정, 조회하는 api 이다. 

( 이정도는 문서 만드려고 글 보러오신 분들이라면 다 알거라.. 생각하기 때문에 api 코드에 대한 설명은 생락하도록 하겠습니다..  혹시 질문이 있다면 댓글 남겨주세요 😀)

 

PostCreateRequest 

package com.sample.restDocs.controller.request;

import com.sample.restDocs.vo.Post;

import lombok.Builder;
import lombok.Getter;
import lombok.NoArgsConstructor;

@Getter
@NoArgsConstructor
public class PostCreateRequest
{
	private String title;
	
	private String content;
	
	@Builder
	public PostCreateRequest(String title, String content)
	{
		this.title = title;
		this.content = content;
	}
	
	public Post toEntity()
	{
		return Post.builder()
				.title(title)
				.content(content)
				.build();
	}
}

 

PostEditRequest 

package com.sample.restDocs.controller.request;

import lombok.Builder;
import lombok.Getter;
import lombok.NoArgsConstructor;

@Getter
@NoArgsConstructor
public class PostEditRequest
{
	private String title;
	private String content;
	
	@Builder
	public PostEditRequest(String title, String content)
	{
		this.title = title;
		this.content = content;
	}
}

 

-> 여기서 PostCreateRequest와 PostEditRequest 를 왜 분리했는지 이해 안될 수도 있다. 

왜냐하면 코드가 거의 똑같기 때문 !! 

사실 샘플 프로젝트라 같아 보이는 것이다. 운영 환경에서는 글 작성, 수정 모두 요구하는 데이터가 다를 수 있는데 이걸 하나로 통일해서 사용하는 건 아니라고 생각했다. 그냥 필요한 데이터만 딱 있는 dto를 만들고 싶었다. 

(굳이 샘플프로젝트에서 이렇게 안나눠도 된다!! 선택 사항이다.) 

(우리 xx에선 하나의 vo에 다 때려넣는데... 그러면 하나의 vo에 불필요한 데이터가 너무 많이 들어가고,,, 한 vo에 값이 20개가 되기도 한다... 왜 이렇게 하는지 도저히 모르겠지만.. dto 만들었다가 삭제하라고 한 소리들어서... 샘플 프로젝트에서만큼이라도 내 맘대로 한다!!!! ㅋㅋ 사족임.. 넘어가세요 ) 

 

ApiResponse

package com.sample.restDocs.controller.response;

import org.springframework.http.HttpStatus;

import lombok.Getter;

@Getter
public class ApiResponse<T>
{
	private int code;
	
	private HttpStatus status;
	private String message;
	
	private T data;
	
	public ApiResponse(HttpStatus status, String message, T data)
	{
		this.code = status.value();
		this.status = status;
		this.message = message;
		this.data = data;
	}
	
	public static <T> ApiResponse<T> of(HttpStatus status, String message, T data)
	{
		return new ApiResponse<>(status, message, data);
	}
	
	public static <T> ApiResponse<T> of(HttpStatus status, T data)
	{
		return new ApiResponse<>(status, status.name(), data);
	}
	
	public static <T> ApiResponse<T> ok(T data)
	{
		return of(HttpStatus.OK, data);
	}
}

-> 컨트롤러에서 그냥 vo 객체를 넘겨도 되겠지만.. 보통은 클라이언트와 협의해서 어떤 형식으로 줄 지 정한다. 

그러므로 code, message, status, data 정도로 해서 ApiResponse를 만들었다. 

 

 

PostService 

package com.sample.restDocs.service;

import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

import com.sample.restDocs.controller.request.PostCreateRequest;
import com.sample.restDocs.controller.request.PostEditRequest;
import com.sample.restDocs.repository.PostRepository;
import com.sample.restDocs.service.response.PostResponse;
import com.sample.restDocs.vo.Post;

import lombok.RequiredArgsConstructor;

@RequiredArgsConstructor
@Service
public class PostService
{
	private final PostRepository postRepository;
	
	public PostResponse getPost(Long postId)
	{
		Post post = postRepository.findById(postId).orElseThrow(() -> new RuntimeException("해당 Post는 존재하지 않습니다."));
		
		return PostResponse.builder().title(post.getTitle())
				.content(post.getContent()).build();
	}
	
	public PostResponse writePost(PostCreateRequest request)
	{
		Post requestPost = request.toEntity();
		
		Post save = postRepository.save(requestPost);
		
		return PostResponse.builder().title(save.getTitle())
				.content(save.getContent()).build();
	}
	
	@Transactional
	public PostResponse editPost(Long postId, PostEditRequest request)
	{
		Post post = postRepository.findById(postId).orElseThrow(() -> new RuntimeException("해당 Post는 존재하지 않습니다."));
		
		post.change(request.getTitle(), request.getContent());
		
		return PostResponse.builder().title(post.getTitle())
				.content(post.getContent()).build();
	}
}

 

PostResponse

package com.sample.restDocs.service.response;

import lombok.Builder;
import lombok.Getter;

@Getter
public class PostResponse
{
	private String title;
	private String content;
	
	@Builder
	public PostResponse(String title, String content)
	{
		this.title = title;
		this.content = content;
	}
}

-> 여기서 또 의아한 ? 사람들이 있을 것 같다. 

왜 서비스 까지 이렇게 만드냐!! 할 수 있다. 하지만 컨트롤러에서는 값 체크도 해야하고, 이런 로직이 들어갈 건데, 서비스에서도 이 객체를 가져와 사용하기보다는 컨트롤러와 서비스는 분리해서 사용하는게 더 낫다~ 라는 강의를 들었다. 

컨트롤러 정책을 서비스까지 가져오지 마라~ 뭐 이런 것 같다.

(이것도 사실 샘플 프로젝트에서까지 할 필요는 없지만 나는 습관 들이고 싶었다.) 

 

PostRepository 

package com.sample.restDocs.repository;

import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.stereotype.Repository;

import com.sample.restDocs.vo.Post;

@Repository
public interface PostRepository extends JpaRepository<Post, Long>
{
}

 

 

*문서작성 샘플 프로젝트 코드 (테스트 코드) 

PostControllerTest 

package com.sample.restDocs.controller;

import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.http.MediaType;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.ResultActions;
import org.springframework.test.web.servlet.request.MockMvcRequestBuilders;
import org.springframework.test.web.servlet.result.MockMvcResultHandlers;
import org.springframework.test.web.servlet.result.MockMvcResultMatchers;

import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.sample.restDocs.controller.request.PostCreateRequest;
import com.sample.restDocs.controller.request.PostEditRequest;
import com.sample.restDocs.repository.PostRepository;
import com.sample.restDocs.service.PostService;
import com.sample.restDocs.vo.Post;

@AutoConfigureMockMvc // @SpringBootTest 를 사용하는 테스트에서 MockMvc를 사용하는 경우에 사용
@SpringBootTest
class PostControllerTest
{
	@Autowired
	private MockMvc mockMvc;
	
	@Autowired
	private ObjectMapper objectMapper;
	
	@Autowired
	private PostService postService;
	
	@Autowired
	private PostRepository postRepository;
	
	@BeforeEach
	void clean() {
		postRepository.deleteAll(); // 테스트 수행 후 데이터 클렌징
	}
	
	@DisplayName("글 작성 테스트")
	@Test
	void write() throws Exception
	{
	    // given
		PostCreateRequest request = PostCreateRequest.builder().title("테스트 제목")
				.content("테스트 내용").build();
		
		// when
		ResultActions result = mockMvc.perform(MockMvcRequestBuilders.post("/api/v1/post")
													   .contentType(MediaType.APPLICATION_JSON)
													   .content(objectMapper.writeValueAsString(request)))
										.andDo(MockMvcResultHandlers.print());
		
		// then
		result.andExpect(MockMvcResultMatchers.status().isOk())
				.andExpect(MockMvcResultMatchers.jsonPath("$.code").value("200"))
				.andExpect(MockMvcResultMatchers.jsonPath("$.data.title").value("테스트 제목"))
				.andExpect(MockMvcResultMatchers.jsonPath("$.data.content").value("테스트 내용"));
	}
	
	
	@DisplayName("글 1개를 저장 후 해당 글 조회 테스트")
	@Test
	void get() throws Exception
	{
	    // given
		Post post = Post.builder().title("테스트 제목").content("테스트 내용").build();
		Post response = postRepository.save(post);
		
		// when
		ResultActions result = mockMvc.perform(MockMvcRequestBuilders.get("/api/v1/post/{postId}", response.getId()))
				.andDo(MockMvcResultHandlers.print());
		
		// then
		result.andExpect(MockMvcResultMatchers.status().isOk())
				.andExpect(MockMvcResultMatchers.jsonPath("$.code").value("200"))
				.andExpect(MockMvcResultMatchers.jsonPath("$.data.title").value("테스트 제목"))
				.andExpect(MockMvcResultMatchers.jsonPath("$.data.content").value("테스트 내용"));
	}
	
	
	@DisplayName("글 1개를 수정 후 해당 글 조회 테스트")
	@Test
	void update() throws Exception
	{
	    // given
		Post post = Post.builder().title("테스트 제목").content("테스트 내용").build();
		Post response = postRepository.save(post);

		PostEditRequest editRequest = PostEditRequest.builder().title("테스트 제목 수정!").content("테스트 내용 수정!").build();
		
		// when
		ResultActions result = mockMvc.perform(MockMvcRequestBuilders.post("/api/v1/post/{postId}", response.getId())
								.contentType(MediaType.APPLICATION_JSON)
								.content(objectMapper.writeValueAsString(editRequest)))
				.andDo(MockMvcResultHandlers.print());
		
		// then
		result.andExpect(MockMvcResultMatchers.status().isOk())
				.andExpect(MockMvcResultMatchers.jsonPath("$.code").value("200"))
				.andExpect(MockMvcResultMatchers.jsonPath("$.data.title").value("테스트 제목 수정!"))
				.andExpect(MockMvcResultMatchers.jsonPath("$.data.content").value("테스트 내용 수정!"));
	}
	
}

 

-> 이건 그냥 PostController를 테스트 하는 코드이다. (참고..ㅎ) 

사실 테스트 코드를 작성하는 법을 이제 막 배워서 공부하고 하는 단계라.. 테스트 하는 코드가 완벽하다고 할 수는 없지만 일단 저는 샘플 프로젝트로 만든 api 테스트를 이렇게 작성했습니다. 

(그리고 Service 도 따로 테스트하는게 맞는데.. 시간관계상 저는 생략했지만..만들어보시길... Service단 테스트도 해야 합니다!!) 

 

 

RestDocsSupport

package com.sample.restDocs.docs;

import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.extension.ExtendWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs;
import org.springframework.boot.test.context.SpringBootTest;
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 com.fasterxml.jackson.databind.ObjectMapper;

import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.documentationConfiguration;

/**
 * Spring REST Docs 환경 클래스
 */
@AutoConfigureRestDocs( // Spring REST Docs 를 사용하기 위해 MockMvc 빈 커스텀
		uriScheme = "https", uriHost = "sample.restDocs.com"
)
@SpringBootTest
@ExtendWith(RestDocumentationExtension.class)
public class RestDocsSupport
{
	protected MockMvc mockMvc;
	
	@Autowired
	protected ObjectMapper objectMapper;
	
	@BeforeEach
	void setUp(WebApplicationContext webApplicationContext, RestDocumentationContextProvider restDocumentation)
	{
		// @AutoConfigureMockMvc 를 통한 자동주입이 아니라 테스트 전에 미리 mockMvc 세팅하는 작업
		this.mockMvc = MockMvcBuilders.webAppContextSetup(webApplicationContext)
				.apply(documentationConfiguration(restDocumentation))
				.build();
	}
	
	
}

-> Rest Docs 문서를 만들기 위한 환경 설정? 이라고 할 수 있다. 

우선 @ExtendWith(RestDocumentationExtension.class)를 추가해줘야 한다. 

그리고 @AutoConfigureRestDocs는 Spring REST Docs 를 사용하기 위해 MockMvc 빈 커스텀 하는 거라고 한다..! 

 

-> @BeforeEach를 통해 테스트 수행 전에 MockMvcRestDocumentationConfigurer. documentationConfiguration()의 정적 메서드 에서 이 클래스의 인스턴스를 얻는다.

 

 

PostControllerDocsTest 

package com.sample.restDocs.docs;

import java.util.List;

import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.mockito.Mock;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.MediaType;
import org.springframework.restdocs.mockmvc.MockMvcRestDocumentation;
import org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders;
import org.springframework.restdocs.payload.FieldDescriptor;
import org.springframework.restdocs.payload.JsonFieldType;
import org.springframework.restdocs.payload.PayloadDocumentation;
import org.springframework.restdocs.request.RequestDocumentation;
import org.springframework.test.web.servlet.ResultActions;
import org.springframework.test.web.servlet.result.MockMvcResultHandlers;
import org.springframework.test.web.servlet.result.MockMvcResultMatchers;

import com.epages.restdocs.apispec.MockMvcRestDocumentationWrapper;
import com.epages.restdocs.apispec.ResourceDocumentation;
import com.epages.restdocs.apispec.ResourceSnippetParameters;
import com.epages.restdocs.apispec.Schema;
import com.sample.restDocs.controller.request.PostCreateRequest;
import com.sample.restDocs.controller.request.PostEditRequest;
import com.sample.restDocs.repository.PostRepository;
import com.sample.restDocs.vo.Post;

public class PostControllerDocsTest extends RestDocsSupport
{
    @Autowired
    private PostRepository postRepository;
    
    protected List<FieldDescriptor> defaultResponseFieldDescriptors = new java.util.ArrayList<>(
          List.of(
                PayloadDocumentation.fieldWithPath("code").type(JsonFieldType.NUMBER).description("응답 코드"),
                PayloadDocumentation.fieldWithPath("status").type(JsonFieldType.STRING).description("응답 상태"),
                PayloadDocumentation.fieldWithPath("message").type(JsonFieldType.STRING).description("응답 메시지"),
                PayloadDocumentation.fieldWithPath("data").type(JsonFieldType.OBJECT).description("응답 데이터")
          ));
    
    @DisplayName("글 하나를 작성하면 정상적으로 저장된다.")
    @Test
    void write() throws Exception
    {
       // given
       PostCreateRequest request = PostCreateRequest.builder().title("테스트 제목")
             .content("테스트 내용").build();
       
       defaultResponseFieldDescriptors.add(PayloadDocumentation.fieldWithPath("data.title").description("post 제목"));
       defaultResponseFieldDescriptors.add(PayloadDocumentation.fieldWithPath("data.content").description("post 내용"));
       
       // when
       ResultActions result = mockMvc.perform(RestDocumentationRequestBuilders.post("/api/v1/post")
                   .contentType(MediaType.APPLICATION_JSON)
                   .content(objectMapper.writeValueAsString(request)))
                   .andDo(MockMvcResultHandlers.print());

       // then
       result.andExpect(MockMvcResultMatchers.status().isOk())
             .andDo(MockMvcRestDocumentation.document("post-write", // REST Docs
                                            RestDocsUtils.getDocumentRequest(),
                                            RestDocsUtils.getDocumentResponse(),
                                            PayloadDocumentation.requestFields( // 요청 데이터 스펙
                                                 PayloadDocumentation.fieldWithPath("title").description("post 제목").optional(),
                                                 PayloadDocumentation.fieldWithPath("content").description("post 내용")
                                            ),
                                            PayloadDocumentation.responseFields( // 응답 데이터 스펙
                                                  defaultResponseFieldDescriptors
                                            )
             ));
       ;
    }
    
    @DisplayName("글 1개를 저장하고 조회하는 테스트")
    @Test
    void get() throws Exception
    {
       // given
       Post post = Post.builder().title("테스트 제목").content("테스트 내용").build();
       Post response = postRepository.save(post);
       
       defaultResponseFieldDescriptors.add(PayloadDocumentation.fieldWithPath("data.title").description("post 제목"));
       defaultResponseFieldDescriptors.add(PayloadDocumentation.fieldWithPath("data.content").description("post 내용"));
       
       // when
       ResultActions result = mockMvc.perform(RestDocumentationRequestBuilders.get("/api/v1/post/{postId}", response.getId()))
                               .andDo(MockMvcResultHandlers.print());
       
       // then
       result.andExpect(MockMvcResultMatchers.status().isOk())
             .andDo(MockMvcRestDocumentation.document("post-get", // REST docs
                                            RestDocsUtils.getDocumentResponse(),
                                            RequestDocumentation.pathParameters(
                                                  RequestDocumentation.parameterWithName("postId").description("post Id")
                                            ),
                                            PayloadDocumentation.responseFields(
                                                  defaultResponseFieldDescriptors
                                            )
             ));
       
    }
    
    @DisplayName("글 1개를 수정 후 해당 글 조회 테스트")
    @Test
    void update() throws Exception
    {
       // given
       Post post = Post.builder().title("테스트 제목").content("테스트 내용").build();
       Post response = postRepository.save(post);
       
       PostEditRequest editRequest = PostEditRequest.builder().title("테스트 제목 수정!").content("테스트 내용 수정!").build();
       
       defaultResponseFieldDescriptors.add(PayloadDocumentation.fieldWithPath("data.title").description("post 제목"));
       defaultResponseFieldDescriptors.add(PayloadDocumentation.fieldWithPath("data.content").description("post 내용"));
       
       // when
       ResultActions result = mockMvc.perform(
                   RestDocumentationRequestBuilders.post("/api/v1/post/{postId}", response.getId())
                         .contentType(MediaType.APPLICATION_JSON)
                         .content(objectMapper.writeValueAsString(editRequest)))
             .andDo(MockMvcResultHandlers.print());
       
       // then
       result.andExpect(MockMvcResultMatchers.status().isOk())
             .andDo(MockMvcRestDocumentation.document("post-update", // REST Docs
                                            RestDocsUtils.getDocumentRequest(),
                                            RestDocsUtils.getDocumentResponse(),
                                            RequestDocumentation.pathParameters(
                                                  RequestDocumentation.parameterWithName("postId").description("post Id")
                                            ),
                                            PayloadDocumentation.requestFields(
                                              PayloadDocumentation.fieldWithPath("title").type(JsonFieldType.STRING).description("post 제목").optional(),
                                              PayloadDocumentation.fieldWithPath("content").type(JsonFieldType.STRING).description("post 내용")
                                            ),
                                            PayloadDocumentation.responseFields(
                                                  defaultResponseFieldDescriptors
                                            )
                                            ));
    }
}

-> 이렇게 테스트 코드 와 문서 작성 코드를 만들어주면 된다. 

 

그리고 bootJar 실행하면 

스니펫이 생성된다. 

-> 그리고 src/main/resources/static/docs로 index.html 로 변환되어 copy 된 것도 확인할 수 있다. 

 

 

스니펫 사용 코드

index.adoc

= RestDocs Test API
:doctype: book
:icons: font
:source-highlighter: highlightjs
:toc: left
:toclevels: 2
:sectlinks:

== 글 작성

=== 요청
include::{snippets}/post-write/http-request.adoc[]

=== 응답
include::{snippets}/post-write/http-response.adoc[]

include::{snippets}/post-write/response-fields.adoc[]

== 글 단건 조회

=== 요청
include::{snippets}/post-get/http-request.adoc[]

include::{snippets}/post-get/path-parameters.adoc[]

=== 응답

include::{snippets}/post-get/http-response.adoc[]

include::{snippets}/post-get/response-fields.adoc[]

-> 생성된 스니펫을 사용하기 전에 소스 파일을 생성해야 한다. 

src/docs/asciidoc에 index.adoc 을 만들고 이런식으로 스니펫들을 조합해서 문서를 만드는 것이다. 

adoc 문서는 커스텀 가능하고, adoc 문법을 공부해서 적용하면 된다. 

https://docs.asciidoctor.org/ → asciidoctor 공식 문서

 

 

결과 화면 

지금은 샘플 프로젝트이므로 http://localhost:8080/docs/index.html 에서 파일 api 문서를 확인할 수 있다.

 

 

 

 

😎 간단하게 Spring REST Docs 를 이용해서 api 문서를 만드는 방법을 알아봤다.

공식 문서만 볼 때 까지는 ??? 하는 이해 안되는 부분들이 있었는데 역시 직접 만들어보고, 오류 나면 찾아도 보고 하면서 이해하고 결과 화면을 보니까 이해가 더 잘 된 것 같다. 

사실 Spring REST Docs 는 개발자가 얼마나 공들여서? 작성하느냐에 따라서 퀄리티는 달라질 것 같다.

하지만 뭐.. 이정도만 해도 깔끔하니 문서보는데 어렵지 않다고 생각하는데... 이건 내 생각일 뿐.. ㅋ 

이건 진짜 초간단으로 사용 방법을 익히기 위해 만든 프로젝트이므로 실전에서는 더 신경써서 테스트도 수행해야 하고, 문서를 만들어야 한다. 

 

Spring REST Docs를 실무에서 이용한다면 먼저 api 문서가 필요할 텐데 그럴때 어떻게 service.. 등등을 언제 만들어서 문서 공유하겠는가..! 

우선 tdd로 한다고 생각하고 ControllerTest만 Mock처리?해서 테스트 코드 작성후 Spring rest doc으로 빠르게 문서만 작성해서 클라이언트와 공유하고, 그 뒤에 비지니스 로직을 처리하는 방법으로 이용하면 될 것 같다.