[Kotlin / Spring] Spring Rest Docs 1탄 - 시작하기 : application/json

[1] 공식문서

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

Spring REST Docs

[2] 세팅하기

[build.gradle.kts]

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

dependencies {
    asciidoctorExt("org.springframework.restdocs:spring-restdocs-asciidoctor:2.0.5.RELEASE") // 2번

    testImplementation("org.springframework.restdocs:spring-restdocs-mockmvc") // 3번
    testImplementation("org.springframework.restdocs:spring-restdocs-asciidoctor") // 4번
}

tasks {
    val snippetsDir by extra { file("build/generated-snippets") } // 5번

    test { // 6번 : test Task 의 output 디렉토리 설정
        outputs.dir(snippetsDir)
        useJUnitPlatform()
    }

    asciidoctor { // asciidoctor Task 생성
        configurations(asciidoctorExt.name)
        inputs.dir(snippetsDir) // 7번 : asciidoctor Task 의 input 디렉토리 설정

        dependsOn(test)
        doLast { // 8번
            copy {
                from("build/docs/asciidoc")
                into("src/main/resources/static/docs")
            }
        }
    }

- 1번 : 플러그인 추가

- 2번 : asciidoctor 의존성 추가

- 3번 : spring rest docs 의존성 추가 (mockMvc)

- 4번 : spring rest docs 의존성 추가 (asciidoctor)

- 5번 : snippets 경로 설정

- 6번 : test Task의 output 디렉토리 설정

- 7번 : asciidoctor Task의 input 디렉토리 설정

- 8번 : 테스트 코드 실행 종료 후 파일 복붙하는 설정 (from 하위 파일을 into 폴더 하위로 복제한다)

 

[3] 테스트코드 작성하기

1. abstract class 작성

우아한 형제들 블로그를 참고하여 작성하였다.

package io.my.project

import com.fasterxml.jackson.databind.ObjectMapper
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc
import org.springframework.boot.test.context.SpringBootTest
import org.springframework.context.annotation.ComponentScan
import org.springframework.test.web.servlet.MockMvc

@SpringBootTest
@AutoConfigureRestDocs // REST Docs 설정
@AutoConfigureMockMvc
@ComponentScan(basePackages = ["io.gbike.hwikgo"]) // 컴포넌트 스캔 범위 지정
abstract class ApiDocumentationTest : BaseMockData() {
    @Autowired
    protected lateinit var mockMvc: MockMvc

    @Autowired
    protected lateinit var objectMapper: ObjectMapper
}

 

? SpringBootTest

여기서 `SpringBootTest` 대신 `WebMvcTest` 를 사용하여 빌드속도를 좀더 빠르게 할 수 있지만 테스트하려는 Controller 에 연결되어있는 많은 Service들과 Service에서 또 참고하는 유틸성 컴포넌트 등 일일이 주입해주어야 할 의존성이 너무 많은듯 하여 일단 SpringBootTest 어노테이션을 사용하였다.

### : MockMvc

spring REST Docs 문서화를 위해선 MockMvc 의 perform을 수행해야 한다. 동일하게 사용되는 객체이므로 abstract에서 생성했다.

 

2. 테스트 코드 작성

먼저 테스트 코드 작성을 위해 controller에 테스트 대상 코드를 작성해 주었다.

@RestController
class HealthcheckController() {
    @GetMapping("/tmp")
    fun tmp(requestDto: TmpRequestDto): TmpResponseDto {
        val recommendEmail = requestDto.name + "@gmail.com"
        val responseDto =
            TmpResponseDto(
                code = 200,
                email = recommendEmail,
                message = "hello, ${requestDto.nickname ?: "guest"}",
            )
        return responseDto
    }

    data class TmpRequestDto(
        val userId: Int = 1,
        val name: String = "",
        val nickname: String = "",
        val age: Int = 1,
        val productName: String = "",
        val hobby: MutableList<String> = mutableListOf(),
        val address: TmpAddress = TmpAddress(city = "", street = "", zipcode = 0),
    )

    data class TmpAddress(
        val city: String,
        val street: String,
        val zipcode: Int,
    )

    data class TmpResponseDto(
        val code: Int,
        val email: String,
        val message: String = "",
    )
}

그리고 나서 해당 controller 를 호출할 테스트 코드를 작성해 주었다. 이때 호출당시의 content-type 에 따라 사용하는 메소드가 달라진다.

- content-type : x-www-form-urlencoded

요청을 보내는 쪽에서 body가 `x-www-form-urlencoded` 타입일 경우 formParameters 를 사용한다.

해당 방식은 다음 글에서 다루도록 하겠다.

- content-type : application/json

요청을 보내는 쪽에서 body가 `application/json` 타입일 경우 requestFields 를 사용한다.

package io.myproject.controller

import io.myproject.ApiDocumentUtils.Companion.documentRequest
import io.myproject.ApiDocumentUtils.Companion.documentResponse
import io.myproject.ApiDocumentationTest
import org.junit.jupiter.api.Test
import org.springframework.http.MediaType
import org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document
import org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders
import org.springframework.restdocs.payload.PayloadDocumentation.*
import org.springframework.test.web.servlet.result.MockMvcResultMatchers

class HealthcheckControllerTest : ApiDocumentationTest() {
    @Test
    fun tmpTest() {
        // given
        val re =
            HealthcheckController.TmpRequestDto(
                userId = 1,
                name = "tester1",
                nickname = "apple",
                age = 30,
                productName = "잘팔리는필통",
                hobby = mutableListOf("수영", "독서"),
                address =
                    HealthcheckController.TmpAddress(
                        city = "서울시 강남구 역삼동",
                        street = "123-456",
                        zipcode = 123,
                    ),
            )

        // when
        val res =
            this.mockMvc.perform(
                RestDocumentationRequestBuilders
                    .get("$domain/tmp")
                    .contentType(MediaType.APPLICATION_JSON)
                    .content(objectMapper.writeValueAsString(re))
                    .accept(MediaType.APPLICATION_JSON),
            )

        res
            .andExpect(MockMvcResultMatchers.status().isOk)
            .andDo(
                document(
                    "docs_json",
                    documentRequest,
                    documentResponse,
                    requestFields(
                        fieldWithPath("userId").description("유저Id").optional(),
                        fieldWithPath("name").description("이름").optional(),
                        fieldWithPath("nickname").description("닉네임").optional(),
                        fieldWithPath("age").description("나이").optional(),
                        fieldWithPath("productName").description("상품명").optional(),
                        fieldWithPath("hobby").description("취미").optional(),
                        fieldWithPath("address").description("주소").optional(),
                        fieldWithPath("address.city").description("도시").optional(),
                        fieldWithPath("address.street").description("도로명").optional(),
                        fieldWithPath("address.zipcode").description("우편번호").optional(),
                    ),
                    responseFields(
                        fieldWithPath("code").description("code").optional(),
                        fieldWithPath("email").description("이메일").optional(),
                        fieldWithPath("message").description("메시지").optional(),
                    ),
                ),
            )
    }
}

 

[4] 문서 생성하기

1. 테스트 실행 : adoc 파일 생성

먼저 작성한 테스트코드가 올바르게 실행되는지 확인한다. 테스트가 성공했다면 `build/generated-snippets` 에 테스트코드에서 지정한 documentdml identifier 이름의 폴더가 있고 그 아래에 사진과 같은 adoc 파일이 생성되어 있을 것이다.

 

- curl-request.adoc : curl 요청 형식으로 작성된 파일

- form-parameters : 본인의 테스트 코드 request body가 form-data 형식이어서 `formParameters`를 사용했기에 생성된 파일

- http-request : http 요청 파일

- http-response : http 응답 파일

- httpie-request : http client 요청 파일

- response-fields : 본인 테스트 코드 `responseFields`에 의해 생성된 파일

 

 

 

 

2. rest docs 포맷 설정 : index.adoc

테스트코드 실행으로 생성된 여러가지 adoc 파일을 활용해 rest docs를 구성해야 한다.

`src/docs/asciidoc/index.adoc`을 다음과 같이 작성하였다.

# REST API

## REST DOCS EXAMPLE

### [http : 요청]
include::{snippets}/docs_json/http-request.adoc[]

#### [요청 필드]
include::{snippets}/docs_json/request-fields.adoc[]

### [http : 응답]
include::{snippets}/docs_json/http-response.adoc[]

#### [응답 필드]
include::{snippets}/docs_json/response-fields.adoc[]

플러그인을 설치하면 다음와 같이 작성했을때 어떻게 보여지는지 바로 확인할 수 있다.

3. html 문서 확인

이제 프로젝트를 빌드하면 위의 adoc 파일의 내용이 index.adoc의 형식으로 index.html 파일로 변환된다. 또한  build.gradle.kts 에 작성했던 아래 설정으로 인해 `build/docs/asciidoc` 에 있는 파일이 `src/main/resources/static/docs` 로 복제 된다.

tasks {
    ... (생략) ...
    asciidoctor {
    	... (생략) ...
        dependsOn(test)
        doLast {
            copy {
                from("build/docs/asciidoc")
                into("src/main/resources/static/docs")
            }
        }
    }

 

해당 resources 하위에 존재해야지만 url path로 접근 할 수 있는데 이때 application 파일에 아래의 항목이 true 로 되어있어야 스프링 어플리케이션의 기본 정적 리소스 매핑을 사용할 수 있다.

spring:
    web:
        resources:
            add-mappings: true # 정적 리소스 매핑 활성화

 

 

4. /docs/index.html 로 발행된 문서 확인

정적 리소스 매핑으로 도메인 뒤에 `/docs/index.html` 를 입력하면 `main/resources/static/docs/index.html` 에 접근 할 수 있다.

참고로 build 로 html문서 생선 전에 `localhost:8080/docs/index.html` 로 접속하면 그러한 리소스는 없다는 오류가 뜬다.

테스트코드가 성공했다고 하여도 전체적인 build가 성공해야지만 docs가 생성된다는것!!

BUILD SUCCESSFUL in 24s

 

문서 생성 확인 완료!!

다음 2탄은 content-type 이 x-www-form-urlencoded 일때 문서 생성하는 방법에 대해 다뤄보도록 하겠다.