[SpringBoot] Spring Rest Docs 적용 (gradle 7버전)

싸피에서 진행한 공통프로젝트 때 API 명세서로 Swagger가 아닌 Spring Rest Docs를 채택했다. 그 때 적용하는 법을 노션에 대충 적어놨는데 이번에 적용하면서 깔끔하게(?) 정리해보려고 한다.

 

👍🏻 내가 생각했을 때 Spring Rest Docs의 장점

- 테스트가 성공해야 문서화가 되기때문에 항상 최신화 되엉있고 품질을 보장할 수 있다.

- 문서화 됐을 때 Swagger보다는 프론트가 쉽게 이해할 수 있다고 생각한다.

- Request, Response에 관한 설명을 어노테이션이 아닌 테스트 시 작성할 수 있어 spring 서버의 코드가 좀 더 깔끔해보인다.

 

👎🏻 Spring Rest Docs의 단점

- 테스트 코드 짜는게 너무너무너무 귀찮다... 정말로...

 

단점을 잘 극복하면 뿌듯한 결과물이 나온다...하하...

 

---

🛠 나의 개발 환경

• Spring Boot 2.7.3
• Gradle 7.x
• Java 8

⚠️ Spring Rest Docs 적용하기 전에 꼭 확인해 봐야 할 것 : Gradle 버전이다.

gradle의 버전에 따라 Spring Rest Docs 적용법이 달라진다!!! 플러그인부터 snippet 생성 경로까지 어마무시하게 다르니까 꼭 확인하는게 좋다...

 

먼저 gradle/wrapper/gradle-wrapper.properties 를 들어간다.

이게 보이는 곳에서 gradle 버전을 확인할 수 있다. 나는 7 버전을 사용 중이다!

 

✔️ gradle의 버전이 7 이상이면 org.asciidoctor.jvm.convert 라는 것을 사용한다.

gradle 6 버전은 구글링하면 엄청나오기 때문에 안쓰도록 하겠다...(귀찮아서가 절대 아님...ㅎ)

 

---

👩🏻‍💻 build.gradle

플러그인 및 의존성 추가

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

dependencies {
	...
    
	// spring rest docs
	asciidoctorExtensions 'org.springframework.restdocs:spring-restdocs-asciidoctor'
	testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
    
	...
}

configurations {
	asciidoctorExtensions
}

snippet 생성 디렉토리 설정

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

test {
	outputs.dir snippetsDir
	finalizedBy 'asciidoctor'
}

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

asciidoctor 설정

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

asciidoctor.doFirst {
	delete file('src/main/resources/static/docs')
}

bootJar 설정

bootJar {
	dependsOn asciidoctor
	copy {
		from "build/docs/asciidoc"
		into "src/main/resources/static/docs"
	}
}

 

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

build {
	dependsOn copyDocument
}

 

이렇게 추가하면 완료!!

---

👩🏻‍💻 테스트 코드 작성

나는 mockMvc 기반으로 테스트 코드를 작성하였다.

mockMvc로 테스트 코드 작성 시 @AutoConfigureMockMvc와 @AutoConfigureRestDocs 어노테이션을 꼭(?) 달아야 한다.

흠... 근데 이번 프로젝트에서 @AutoConfigureMockMvc 어노테이션 추가를 안했는데 성공했다..... 왜지....(?) 

 

아래는 이번 특화프로젝트에서 문서화한 API 중 하나이다.

Given-When-Then 패턴으로 작성해보았다.

@WebMvcTest(YoutuberApiController.class)
@AutoConfigureRestDocs
public class YoutuberRestDocsTest {

    @Autowired
    private MockMvc mockMvc;

    @MockBean
    private YoutuberService youtuberService;

    @Test
    public void youtuber_검색() throws Exception {
        // given
        String request = "삼성청년";
        List<YoutuberResponseDto> response = new ArrayList<>();
        response.add(YoutuberResponseDto.builder()
                .channelId("UC_XI3ByFO1uZIIH-g-zJZiw")
                .channelName("삼성청년SW아카데미 Youtube채널 HELLOSSAFY")
                .thumbnail("https://yt3.ggpht.com/ytc/AMLnZu9qdR9T9_9OXz27_3lZVs4hfwECef2oUSylrcQv=s800-c-k-c0x00ffffff-no-rj").build());
        given(youtuberService.searchYoutuber(anyString())).willReturn(response);

        // when, then
        mockMvc.perform(RestDocumentationRequestBuilders.get("/api/v1/youtubers/{keyword}", request))
                .andExpect(status().isOk())
                .andDo(document("youtuber-search",
                        preprocessRequest(prettyPrint()),
                        preprocessResponse(prettyPrint()),
                        pathParameters(
                                parameterWithName("keyword").description("검색할 단어")
                        ),
                        responseFields(
                                fieldWithPath("success").description("API 요청 성공 여부").type(JsonFieldType.BOOLEAN),
                                fieldWithPath("data").description("Response data").type(JsonFieldType.ARRAY)
                        ).andWithPrefix("data[].",
                                fieldWithPath("channelId").description("유튜버 채널 id").type(JsonFieldType.STRING),
                                fieldWithPath("channelName").description("유튜버 채널명").type(JsonFieldType.STRING),
                                fieldWithPath("thumbnail").description("유튜버 썸네일 주소").type(JsonFieldType.STRING))
                        ));
    }
}

 

given

먼저 API request를 하나 만들어주고 그 request에 맞는 response도 생성해준다.

그리고 Mockito의 given().willReturn()을 이용해서 request와 response를 정해놓는다.

Service 로직 검증이 필요한게 아니라 문서화가 목표이기 때문에 이렇게 하는 것 같다...!

 

정말 간단히 mockito 알아보기

🤔 given(A).willReturn(B)?
A라는 서비스가 호출되면 그 결과는 무조건 B라고 설정(?)해두는 것이다.

🤔 given().willReturn()과 when().thenReturn()의 차이?
동작은 똑같다. BDD기반으로 테스트할 경우 //given 절에서 when()을 사용하면 흐름이 이상하다고 생각할까봐 given()이 생겼단다.
그래서 그냥 given()을 썼다.

- import static org.mockito.**Mockito**.*when*
- import static org.mockito.**BDDMockito**.*given*;

 		// given
        String request = "삼성청년";
        List<YoutuberResponseDto> response = new ArrayList<>();
        response.add(YoutuberResponseDto.builder()
                .channelId("UC_XI3ByFO1uZIIH-g-zJZiw")
                .channelName("삼성청년SW아카데미 Youtube채널 HELLOSSAFY")
                .thumbnail("https://yt3.ggpht.com/ytc/AMLnZu9qdR9T9_9OXz27_3lZVs4hfwECef2oUSylrcQv=s800-c-k-c0x00ffffff-no-rj").build());
        given(youtuberService.searchYoutuber(anyString())).willReturn(response);

 

when + then

변수 생성하는게 귀찮아서 합쳐버렸다...ㅎㅎ

mockMvc로 perform을 수행하는데 이 때 MockMvcRequestBuilders이 아닌RestDocumentationRequestBuilders의 메소드를 사용하자!!!

MockMvcRequestBuilders의 메소드들은 Path variables를 사용하는 api에 대해 문서화가 불가능하다....

그냥 처음부터 무조건 RestDocumentationRequestBuilders를 사용하길!!!!!!

// when, then
        mockMvc.perform(RestDocumentationRequestBuilders.get("/api/v1/youtubers/{keyword}", request))
                .andExpect(status().isOk())
                
// -------------------------------------------------------여기서부터 then
                .andDo(document("youtuber-search",
                        preprocessRequest(prettyPrint()),
                        preprocessResponse(prettyPrint()),
                        pathParameters(
                                parameterWithName("keyword").description("검색할 단어")
                        ),
                        responseFields(
                                fieldWithPath("success").description("API 요청 성공 여부").type(JsonFieldType.BOOLEAN),
                                fieldWithPath("data").description("Response data").type(JsonFieldType.ARRAY)
                        ).andWithPrefix("data[].",
                                fieldWithPath("channelId").description("유튜버 채널 id").type(JsonFieldType.STRING),
                                fieldWithPath("channelName").description("유튜버 채널명").type(JsonFieldType.STRING),
                                fieldWithPath("thumbnail").description("유튜버 썸네일 주소").type(JsonFieldType.STRING))
                        ));

 

코드에 대한 짧은 설명을 추가해봤다... 더 자세한건 역시 구글링😇

document("youtuber-search", ...)

문서화할 document의 폴더 이름을 넣어주면 된다.

API가 여러개 존재하면 구분할 수 있게 기능에 대한 설명을 써놓는게 좋은 것 같다.(그냥 내생각ㅎ)

 

preprocessRequest(prettyPrint()),
preprocessResponse(prettyPrint()),

결과물에서 request와 response를 보기 편한 형식으로 출력해주는 용도이다.

이걸 안해주면 한 줄로 쫘라락 나오기 때문에 무조건 하는 걸 추천

 

pathParameters(
        parameterWithName("keyword").description("검색할 단어")
),

request의 path parameter가 존재하면 추가하면된다.

여러 개일 경우 parameterWithName()을 추가하자.

 

requestFields(
    fieldWithPath("stuffName").description("stuff 영문명"),
    fieldWithPath("stuffNameKor").description("stuff 한글명")
),

이건 다른 프로젝트에서 가져온 코드인데

request에 body가 존재하면 이렇게 사용하면 된다!

 

responseFields(
        fieldWithPath("success").description("API 요청 성공 여부").type(JsonFieldType.BOOLEAN),
        fieldWithPath("data").description("Response data").type(JsonFieldType.ARRAY)
)

 response에 들어가는 데이터에 대한 설명을 쓰는 곳이다.

responseFields를 사용하면 response 데이터에 대한 설명을 무조건 다 추가해야하고, relaxedResponseFields였나 암튼 이걸 사용하면 원하는 데이터만 추가할 수 있다.

 

.andWithPrefix("data[].",
        fieldWithPath("channelId").description("유튜버 채널 id").type(JsonFieldType.STRING),
        fieldWithPath("channelName").description("유튜버 채널명").type(JsonFieldType.STRING),
        fieldWithPath("thumbnail").description("유튜버 썸네일 주소").type(JsonFieldType.STRING))
)

저 API 응답에서 data 변수에 실질적인 데이터가 담겨있어서 .andWithPrefix로 data 안에 담겨있는 정보들에 대한 설명을 추가해주었다

---

👩🏻‍💻 HTML 문서 만들기

테스트 코드가 성공적으로 끝난다면, build/generated-snippets에 youtuber-search 폴더가 생긴다.

이걸 기반으로 모든 API 설명이 들어간 adoc 파일을 만들 것이다.  

먼저 /src/docs/asciidoc 폴더에 index.adoc을 생성한다.

 

아래와 같이 폴더별로 추가해주면 드디어 끝이 보인다....

[[Youtuber-검색]]
== Youtuber 검색

=== Http Request
include::{snippets}/youtuber-search/http-request.adoc[]

=== Path parameters
include::{snippets}/youtuber-search/path-parameters.adoc[]

=== Http Response
include::{snippets}/youtuber-search/http-response.adoc[]

=== Response fields
include::{snippets}/youtuber-search/response-fields.adoc[]

---

🥹 완성

./gradlew build를 하고 서버를 실행하면 localhost:8080/docs/index.html에 접속이 가능하고 고생하던 나의 결과물이 보인다...하하

공통 프로젝트 때 15시간 걸려서 만든 명세서....흑흑....