[Spring] RestDocs로 API 문서화를 간단히 해보자

1. build.gradle.kts 설정

• 추가해야 할 부분만 표시해놓았습니다~

import org.jetbrains.kotlin.gradle.tasks.KotlinCompile

plugins {
   ...
   id("com.epages.restdocs-api-spec") version "0.16.0"
   ...
}

group = "com.test"
version = "0.0.1-SNAPSHOT"

java {
   sourceCompatibility = JavaVersion.VERSION_17
}

repositories {
   mavenCentral()
}

dependencies {
   ...
   testImplementation("com.epages:restdocs-api-spec-mockmvc:0.16.2")
}

openapi3 {
   this.setServer("https://localhost:8080") 
   title = "openapi3 test"
   description = "테스트 입니당"
   version = "0.1.0"
   format = "yaml" // or json
}

 

2. API 작성

• 간단한 테스트용 API를 작성한다.

@RestController
class TestController {

    @GetMapping("/test")
    fun getTest(@RequestParam name: String, @RequestParam age: Int) = ResponseEntity<TestResponse>(
        TestResponse(
            200, "Hello $name ($age)."
        ),
        HttpStatus.OK
    )
}

 

3. Test Code 작성

import com.epages.restdocs.apispec.MockMvcRestDocumentationWrapper
import com.epages.restdocs.apispec.ResourceDocumentation.parameterWithName
import com.epages.restdocs.apispec.ResourceSnippetParametersBuilder
import com.epages.restdocs.apispec.SimpleType
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.restdocs.RestDocumentationContextProvider
import org.springframework.restdocs.RestDocumentationExtension
import org.springframework.restdocs.mockmvc.MockMvcRestDocumentation
import org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders.get
import org.springframework.restdocs.payload.JsonFieldType
import org.springframework.restdocs.payload.PayloadDocumentation.fieldWithPath
import org.springframework.test.context.junit.jupiter.SpringExtension
import org.springframework.test.web.servlet.MockMvc
import org.springframework.test.web.servlet.result.MockMvcResultMatchers.status
import org.springframework.test.web.servlet.setup.DefaultMockMvcBuilder
import org.springframework.test.web.servlet.setup.MockMvcBuilders
import org.springframework.web.context.WebApplicationContext

@ExtendWith(RestDocumentationExtension::class, SpringExtension::class)
@SpringBootTest
internal class TestControllerTest {

    private lateinit var mockMvc: MockMvc

    @BeforeEach
    fun setUp(context: WebApplicationContext, restDocumentation: RestDocumentationContextProvider) {
        mockMvc = MockMvcBuilders.webAppContextSetup(context)
            .apply<DefaultMockMvcBuilder>(MockMvcRestDocumentation.documentationConfiguration(restDocumentation))
            .build()
    }

    @Test
    fun `스웨거 테스트`() {
        val name = "mark"
        val age = 20
        mockMvc.perform(
            get("/test?name={name}&age={age}", name, age)
        )
            .andExpect(status().isOk)
            .andDo(
                MockMvcRestDocumentationWrapper.document(
                    identifier = "test",
                    resourceDetails = ResourceSnippetParametersBuilder()
                        .tag("테스트")
                        .description("테스트 입니당")
                        .requestParameters(
                            parameterWithName("name").description("이름").type(SimpleType.STRING),
                            parameterWithName("age").description("나이").type(SimpleType.NUMBER),
                        )
                        .responseFields(
                            fieldWithPath("status").type(JsonFieldType.NUMBER).description("The status."),
                            fieldWithPath("value").type(JsonFieldType.STRING).description("The value."),
                        ),
                ),
            )
    }
}

 

4. run openapi3 

• 테스트코드를 작성한 후, openapi3 를 실행한다.

 

5. openapi3.yaml 확인

• 해당 yaml을 swagger editor(https://editor.swagger.io/)에 붙여넣으면 정상적으로 문서화가 된 것을 확인할 수 있습니다.

아직 테스트 중이라 수정해야할 게 많습니다. 감안해서 확인 부탁드립니다~