[Spring] REST Docs

---

🔎REST Docs란?

• Test 코드 기반으로 Restful API 서비스를 문서화를 도움
• Asciidoctor를 사용하며, 이를 이용해 html을 생성
• 큰 장점은 테스트 코드를 기반으로 문서를 작성한다는 점
• 테스트 통과시 Snippet이 생성됨
• 만약 테스트 실패 시, Snippet이 생성되지 않음

---

💡REST Docs VS Swagger

	REST Docs	Swagger
장점	테스트에 성공해야 문서 작성 가능	API 를 테스트 해 볼수 있는 화면을 제공
	제품 코드에 영향이 없음	테스트 코드가 필요 없으므로 적용하기 쉬움
단점	테스트 코드를 작성해야 하므로 적용이 불편	제품 코드에 어노테이션 추가해야 함
		테스트 기반이 아니기 때문에 100% 정확하지 않을 수 있음

• Swagger 사용 시, 제품 코드에 어노테이션을 추가해야 함
• 때문에 지속적으로 사용 시, 어노테이션이 많이 붙게 되고 가독성이 떨어질 수 있음

---

🔎 들어가기 전에 : build.gradle 추가

: REST Docs를 만들기 위해, 필요한 부분들을 추가해 주었다.

plugins {
   ...
   
   id "org.asciidoctor.jvm.convert" version "3.3.2" /*  추가 */
}

group = 'org.study'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '11'

configurations {
   ...
   
   asciidoctorExtensions /*  추가 */
}

repositories {
   mavenCentral()
}

ext {
   set('snippetsDir', file("build/generated-snippets")) /*  추가 */
}

dependencies {
   
   ...

   /* Rest Docs 추가 */
   testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
   asciidoctorExtensions 'org.springframework.restdocs:spring-restdocs-asciidoctor'

   /* Gson */
   implementation 'com.google.code.gson:gson'
}

/* 아래의 내용들 추가 */

tasks.named('test') {
   outputs.dir snippetsDir
   useJUnitPlatform()
}

tasks.named('asciidoctor') {
   configurations "asciidoctorExtensions"
   inputs.dir snippetsDir
   dependsOn test
}

task copyDocument(type: Copy) {
   dependsOn asciidoctor
   from file("${asciidoctor.outputDir}")
   into file("src/main/resources/static/docs")
}

build {
   dependsOn copyDocument
}

bootJar {
   dependsOn copyDocument
   from("${asciidoctor.outputDir}") {
      into 'static/docs'

   }
}

---

🔎 REST Docs 생성 1 - Test Code 작성

GitHub - Bhinney/Rec_Study: ✨ 공부하면서 기록하는 공간 ✨

1️⃣ 요청과 응답 예쁘게 프린트 하기 위한 Util 추가

public interface ApiDocumentUtils {
	static OperationRequestPreprocessor getRequestPreProcessor() {
		return preprocessRequest(prettyPrint());
	}

	static OperationResponsePreprocessor getResponsePreProcessor() {
		return preprocessResponse(prettyPrint());
	}
}

 

2️⃣ BoardControllerTest 클래스 생성

: 게시물 등록과 수정은 StubData가 아닌 직접 데이터를 입력해주었다.

@WebMvcTest(BoardController.class)
@MockBean(JpaMetamodelMappingContext.class)
@AutoConfigureRestDocs
public class BoardControllerTest {

   @Autowired
   private MockMvc mockMvc;

   @MockBean
   private BoardService boardService;

   @MockBean
   private BoardMapper mapper;

   @Autowired
   private Gson gson;

   @Test
   @DisplayName("게시글 등록 테스트")
   public void postBoardTest() throws Exception {

      /* given */
      BoardDto.Post post = new BoardDto.Post("김이름", "제목입니다.", "내용입니다.");
      String content = gson.toJson(post);

      BoardDto.Response response =
         new BoardDto.Response(1L, "김이름", "제목입니다.", "내용입니다.", LocalDate.now(), LocalDate.now());

      given(mapper.boardPostDtoToBoard(Mockito.any(BoardDto.Post.class))).willReturn(new Board());
      given(boardService.create(Mockito.any(Board.class))).willReturn(new Board());
      given(mapper.boardToBoardResponseDto(Mockito.any(Board.class))).willReturn(response);

      /* when */
      ResultActions actions
         = mockMvc.perform(
         post("/api/boards")
            .accept(MediaType.APPLICATION_JSON)
            .contentType(MediaType.APPLICATION_JSON)
            .content(content)
      );

      /* then */
      actions
         .andExpect(status().isCreated())
         .andExpect(jsonPath("$.nickName").value(post.getNickName()))
         .andExpect(jsonPath("$.title").value(post.getTitle()))
         .andExpect(jsonPath("$.content").value(post.getContent()))
         .andDo(document("post-board",
            getRequestPreProcessor(),
            getResponsePreProcessor(),
            requestFields(
               List.of(
                  fieldWithPath("nickName").type(JsonFieldType.STRING).description("작성자"),
                  fieldWithPath("title").type(JsonFieldType.STRING).description("제목"),
                  fieldWithPath("content").type(JsonFieldType.STRING).description("내용")
               )
            ),
            responseFields(
               List.of(
                  fieldWithPath("boardId").type(JsonFieldType.NUMBER).description("게시판 식별자"),
                  fieldWithPath("nickName").type(JsonFieldType.STRING).description("작성자"),
                  fieldWithPath("title").type(JsonFieldType.STRING).description("제목"),
                  fieldWithPath("content").type(JsonFieldType.STRING).description("내용"),
                  fieldWithPath("createdAt").type(JsonFieldType.STRING).description("최초 작성 일자"),
                  fieldWithPath("modifiedAt").type(JsonFieldType.STRING).description("수정 일자")
               )
            )
         ));
   }

   @Test
   @DisplayName("게시글 수정 테스트")
   public void patchBoardTest() throws Exception {

      /* given */
      long boardId = 1L;
      BoardDto.Patch patch = new BoardDto.Patch("수정된 이름", "수정된 제목입니다.", "수정된 내용입니다.");
      String content = gson.toJson(patch);

      BoardDto.Response response =
         new BoardDto.Response(1L,"수정된 이름", "수정된 제목입니다.", "수정된 내용입니다.", LocalDate.now(), LocalDate.now());

      given(mapper.boardPatchDtoToBoard(Mockito.any(BoardDto.Patch.class))).willReturn(new Board());
      given(boardService.update(Mockito.any(Board.class), Mockito.anyLong())).willReturn(new Board());
      given(mapper.boardToBoardResponseDto(Mockito.any(Board.class))).willReturn(response);

      /* when */
      ResultActions actions
         = mockMvc.perform(
         patch("/api/boards/{boardId}", boardId)
            .accept(MediaType.APPLICATION_JSON)
            .contentType(MediaType.APPLICATION_JSON)
            .content(content)
      );

      /* then */
      actions
         .andExpect(status().isOk())
         .andExpect(jsonPath("$.nickName").value(patch.getNickName()))
         .andExpect(jsonPath("$.title").value(patch.getTitle()))
         .andExpect(jsonPath("$.content").value(patch.getContent()))
         .andDo(document("patch-board",
            getRequestPreProcessor(),
            getResponsePreProcessor(),
            requestFields(
               List.of(
                  fieldWithPath("nickName").type(JsonFieldType.STRING).description("작성자"),
                  fieldWithPath("title").type(JsonFieldType.STRING).description("제목"),
                  fieldWithPath("content").type(JsonFieldType.STRING).description("내용")
               )
            ),
            responseFields(
               List.of(
                  fieldWithPath("boardId").type(JsonFieldType.NUMBER).description("게시판 식별자"),
                  fieldWithPath("nickName").type(JsonFieldType.STRING).description("작성자"),
                  fieldWithPath("title").type(JsonFieldType.STRING).description("제목"),
                  fieldWithPath("content").type(JsonFieldType.STRING).description("내용"),
                  fieldWithPath("createdAt").type(JsonFieldType.STRING).description("최초 작성 일자"),
                  fieldWithPath("modifiedAt").type(JsonFieldType.STRING).description("수정 일자")
               )
            )
         ));
   }

}

 

3️⃣ 테스트 코드를 간결하게 하기 위해 StubData 생성

: 직접 데이터를 입력하는 것이 아닌 StubData를 이용해서 데이터 불러오기

때문에 이후에 테스트 코드 수정을 해볼 예정이다.

public class StubData {
	private static Map<HttpMethod, Object> stubRequestBody;
	static {
		stubRequestBody = new HashMap<>();
		stubRequestBody.put(HttpMethod.POST, new BoardDto.Post("김이름", "제목입니다.", "내용입니다."));
		stubRequestBody.put(HttpMethod.PATCH, new BoardDto.Patch("수정된 이름", "수정된 제목입니다.", "수정된 내용입니다."));
	}

	public static class MockBoard {
		public static Object getRequestBody(HttpMethod method) {
			return stubRequestBody.get(method);
		}

		public static BoardDto.Response getBoardResponse() {
			BoardDto.Response board = BoardDto.Response.builder()
				.boardId(1L)
				.nickName("김이름")
				.title("제목입니다.")
				.content("내용입니다.")
				.createdAt(LocalDate.now())
				.modifiedAt(LocalDate.now())
				.build();

			return board;
		}

		public static Page<Board> getBoardListStubData() {
			Board board1 = Board.builder()
					.nickName("김이름1")
					.title("첫 번째 제목입니다.")
					.content("첫 번째 내용입니다.")
					.build();

			Board board2 = Board.builder()
					.nickName("김이름2")
					.title("두 번째 제목입니다.")
					.content("두 번째 내용입니다.")
					.build();

			Board board3 = Board.builder()
					.nickName("김이름3")
					.title("세 번째 제목입니다.")
					.content("세 번째 내용입니다.")
					.build();

			return new PageImpl<>(List.of(board3, board2, board1),
				PageRequest.of(0, 10, Sort.by("memberId").descending()),3);
		}

		public static List<BoardDto.Response> getBoardListResponse() {
			BoardDto.Response board1 = BoardDto.Response.builder()
				.boardId(1L)
				.nickName("김이름1")
				.title("첫 번째 제목입니다.")
				.content("첫 번째 내용입니다.")
				.createdAt(LocalDate.now())
				.modifiedAt(LocalDate.now())
				.build();

			BoardDto.Response board2 = BoardDto.Response.builder()
				.boardId(2L)
				.nickName("김이름2")
				.title("두 번째 제목입니다.")
				.content("두 번째 내용입니다.")
				.createdAt(LocalDate.now())
				.modifiedAt(LocalDate.now())
				.build();

			BoardDto.Response board3 = BoardDto.Response.builder()
				.boardId(3L)
				.nickName("김이름3")
				.title("세 번째 제목입니다.")
				.content("세 번째 내용입니다.")
				.createdAt(LocalDate.now())
				.modifiedAt(LocalDate.now())
				.build();

			return List.of(
				board3, board2, board1
			);
		}

		public static Board getBoardStubData(long boardId) {
			Board board = Board.builder()
					.nickName("김이름")
					.title("제목입니다.")
					.content("내용입니다.")
					.build();

			return board;
		}
	}
}

 

4️⃣ 테스트 코드를 간결하게 하기 위해 Helper 작성

: 테스트 코드에서 ResultActions을 간결하게 하기 위한 Helper 작성 

public interface ControllerTestHelper<T> {

	default RequestBuilder getRequestBuilder(String url, long sourceId) {
		return get(url, sourceId)
			.accept(MediaType.APPLICATION_JSON);
	}

	default RequestBuilder getRequestBuilder(String url, MultiValueMap<String, String> queryParams){
		return get(url)
			.params(queryParams)
			.accept(MediaType.APPLICATION_JSON);
	}


	default RequestBuilder deleteRequestBuilder(String uri, long sourceId) {
		return delete(uri, sourceId);
	}

	default URI createURI(String url) {
		return UriComponentsBuilder.newInstance().path(url).build().toUri();
	}

	default URI createURI(String url, long resourceId) {
		return UriComponentsBuilder.newInstance().path(url).buildAndExpand(resourceId).toUri();
	}

	default String toJsonContent(T t) {
		Gson gson = new Gson();
		String content = gson.toJson(t);
		return content;
	}
}

 

public interface BoardControllerHelper extends ControllerTestHelper {
	String url = "/api/boards";
	String resource = "/{boardId}";

	default String getBoardURI() {
		return url;
	}


	default String getBoardResourceURI() {
		return url + resource;
	}
}

 

4️⃣ BoardControllerTest 클래스 추가 구현

: 특정 게시물 조회, 게시물 리스트 조회, 게시판 삭제에 대한 테스터는 StubData와 Helper를 이용해 구현하였다.

Helpers는 implements 하여 사용하였다.

@WebMvcTest(BoardController.class)
@MockBean(JpaMetamodelMappingContext.class)
@AutoConfigureRestDocs
public class BoardControllerTest implements BoardControllerHelper {

	@Autowired
	private MockMvc mockMvc;

	@MockBean
	private BoardService boardService;

	@MockBean
	private BoardMapper mapper;

	@Autowired
	private Gson gson;
	
    ...

	@Test
	@DisplayName("특정 게시물 조회 테스트")
	public void getBoardTest() throws Exception {
		/* given */
		long boardId = 1L;
		BoardDto.Response response = StubData.MockBoard.getBoardResponse();

		String url = getBoardResourceURI();

		given(boardService.findBoard(Mockito.anyLong())).willReturn(new Board());
		given(mapper.boardToBoardResponseDto(Mockito.any(Board.class))).willReturn(response);

		/* when */
		ResultActions actions = mockMvc.perform(getRequestBuilder(url, boardId));

		/* then */
		actions.andExpect(status().isOk())
			.andDo(document("get-board",
				getResponsePreProcessor(),
				pathParameters(parameterWithName("boardId").description("게시판 식별자")),
				responseFields(
					List.of(
						fieldWithPath("boardId").type(JsonFieldType.NUMBER).description("게시판 식별자"),
						fieldWithPath("nickName").type(JsonFieldType.STRING).description("작성자"),
						fieldWithPath("title").type(JsonFieldType.STRING).description("제목"),
						fieldWithPath("content").type(JsonFieldType.STRING).description("내용"),
						fieldWithPath("createdAt").type(JsonFieldType.STRING).description("최초 작성 일자"),
						fieldWithPath("modifiedAt").type(JsonFieldType.STRING).description("수정 일자")
					)
				)
			));
	}

	@Test
	@DisplayName("게시물 리스트 조회")
	public void getBoardListTest() throws Exception {
		Page<Board> boardList = StubData.MockBoard.getBoardListStubData();
		List<BoardDto.Response> responseList = StubData.MockBoard.getBoardListResponse();

		String url = getBoardURI();

		MultiValueMap<String, String> queryParams = new LinkedMultiValueMap<>();
		queryParams.add("page", "1");
		queryParams.add("size", "3");

		given(boardService.findBoardList(Mockito.anyInt(), Mockito.anyInt())).willReturn(boardList);
		given(mapper.boardToBoardResponseDto(Mockito.anyList())).willReturn(responseList);

		/* when */
		ResultActions actions = mockMvc.perform(getRequestBuilder(url,queryParams));

		/* then */
		actions.andExpect(status().isOk())
			.andDo(document("get-boardList",
				getRequestPreProcessor(),
				getResponsePreProcessor(),
				requestParameters(
					List.of(
						parameterWithName("page").description("페이지 번호"),
						parameterWithName("size").description("페이지 사이즈")
					)
				),
				responseFields(
					List.of(
						fieldWithPath("[].boardId").type(JsonFieldType.NUMBER).description("게시판 식별자"),
						fieldWithPath("[].nickName").type(JsonFieldType.STRING).description("작성자"),
						fieldWithPath("[].title").type(JsonFieldType.STRING).description("제목"),
						fieldWithPath("[].content").type(JsonFieldType.STRING).description("내용"),
						fieldWithPath("[].createdAt").type(JsonFieldType.STRING).description("최초 작성 일자"),
						fieldWithPath("[].modifiedAt").type(JsonFieldType.STRING).description("수정 일자")
					)
				)
			));
	}

	@Test
	@DisplayName("게시물 삭제 테스트")
	public void deleteBoardTest() throws Exception {
		long boardId = 1L;
		String message = "게시판이 성공적으로 삭제되었습니다.";
		given(boardService.delete(Mockito.anyLong())).willReturn(message);

		String url = getBoardResourceURI();

		/* when */
		ResultActions actions = mockMvc.perform(deleteRequestBuilder(url, boardId));

		actions.andExpect(status().isOk())
			.andDo(document("delete-board",
					pathParameters(parameterWithName("boardId").description("게시판 식별자"))
				)
			);
	}
}

---

🔎 REST Docs 생성 2 - adoc 문서 작성 & Html 생성

1️⃣ Test를 하여 통과가 되면 build 폴더 안에 Snippet이 생성 됨

 

2️⃣ 해당 스니핏을 바탕으로 adoc 문서 작성

GitHub - Bhinney/Rec_Study: ✨ 공부하면서 기록하는 공간 ✨

= 게시판 어플리케이션

:sectnums:
:toc: left
:toclevels: 4
:toc-title: Table of Contents
:source-highlighter: prettify


v1.0.0, 2023.01.04

***

 이 문서는 스프링 공부를 위해 작성된 게시판 CRUD의 문서입니다.

***
== BoardController
==== 게시글 등록
.curl-request
include::{snippets}/post-board/curl-request.adoc[]

.http-request
include::{snippets}/post-board/http-request.adoc[]

.request-fields
include::{snippets}/post-board/request-fields.adoc[]

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

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

=== 게시글 수정
.curl-request
include::{snippets}/patch-board/curl-request.adoc[]

.http-request
include::{snippets}/patch-board/http-request.adoc[]

.request-fields
include::{snippets}/patch-board/request-fields.adoc[]

.http-response
include::{snippets}/patch-board/http-response.adoc[]

.response-fields
include::{snippets}/patch-board/response-fields.adoc[]


=== 특정 게시글 조회

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

.http-request
include::{snippets}/get-board/http-request.adoc[]

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

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


=== 게시글 리스트 조회
.curl-request
include::{snippets}/get-boardList/curl-request.adoc[]

.http-request
include::{snippets}/get-boardList/http-request.adoc[]

.request-parameters
include::{snippets}/get-boardList/request-parameters.adoc[]

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

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

=== 게시글 삭제
.curl-request
include::{snippets}/delete-board/curl-request.adoc[]

.http-request
include::{snippets}/delete-board/http-request.adoc[]

.http-response
include::{snippets}/delete-board/http-response.adoc[]

 

3️⃣ Gradle 에서 bootJar 실행

 

4️⃣ 제대로 실행이 되었다면 resources/static/docs안에 html이 생성

GitHub - Bhinney/Rec_Study: ✨ 공부하면서 기록하는 공간 ✨

 

5️⃣ 해당 html 파일을 크롬으로 열어 보기

: 아래의 일부를 캡쳐해 왔다. 아래의 사진처럼 확인이 가능하다.

---