Restdocs

REST Docs rules

Overview

This document defines rules for writing Spring REST Docs tests using the project's RestDocsSupport base class, Field DSL, and common response patterns.

Key Principle: Extend RestDocsSupport, mock the Facade, and use DocsFieldType and Field DSL for all documentation tests.

Note: Full documentation is available in the .docs/restdocs/ directory.

Document	Contents
.docs/restdocs/01-overview.adoc	Directory structure, core components, DocsFieldType, Field DSL
.docs/restdocs/02-writing-tests.adoc	Step-by-step DocsTest writing guide, common response patterns
.docs/restdocs/03-examples.adoc	HolidayControllerDocsTest analysis, AsciiDoc document authoring
.docs/restdocs/04-reference.adoc	Best practices, troubleshooting, checklist, build commands

Core rules

1. Extend RestDocsSupport

All DocsTests must extend RestDocsSupport.

class MyControllerDocsTest : RestDocsSupport() {

    private val myFacade: MyFacade = mock()

    override fun initController(): Any = MyController(myFacade)
}

2. Mock the Facade

Controllers depend on Facades. Mock the Facade in your DocsTests.

// Good: Mock the Facade
private val holidayFacade: HolidayFacade = mock()
override fun initController(): Any = HolidayController(holidayFacade)

// Bad: Mock the Service directly
private val holidayService: HolidayService = mock()

3. Use DocsFieldType

4. Field DSL (infix functions)

"fieldName" type TYPE means "description"
"fieldName" type TYPE means "description" isOptional true
"fieldName" type TYPE means "description" example "sample value"
"fieldName" type TYPE means "description" withDefaultValue "default"

5. Response strategy

// Subsection strategy (recommended)
responseFields(*responseCommonFieldsSubsection()),
dataResponseFields(
    "id" type NUMBER means "ID",
    "name" type STRING means "이름",
)

6. Pagination response

mockMvc.perform(
    get("/api/resources/{id}", 1)
        .param("page", "0")
        .param("size", "20")
)
    .andExpect(status().isOk)
    .andDo(
        restDocs.document(
            queryParameters(
                *pageRequestFormat().toTypedArray(),
            ),
            responseFields(
                *responseArrayCommonFieldsSubsection(),
                subsectionWithPath("meta.pageInfo").type(JsonFieldType.OBJECT)
                    .optional().description("페이지 정보"),
            ),
            responseFields(
                beneathPath("meta.pageInfo").withSubsectionId("data.page"),
                *pageCommonFormat().toTypedArray(),
            ),
            dataResponseFields(
                "id" type NUMBER means "ID",
            ),
        )
    )

7. Test method naming

Test method names become snippet directory names. Use clear English names.

// Good: Meaningful snippet directory names
fun `get holidays by year`(): Unit { }       // -> get-holidays-by-year/
fun `create holiday`(): Unit { }             // -> create-holiday/

// Bad: Unclear directory names
fun `should return holidays`(): Unit { }     // -> should-return-holidays/

8. Write field descriptions in Korean

IMPORTANT: Write field descriptions in REST Docs in Korean. This is a project convention.

// Good
"data.name" type STRING means "공휴일 이름"

// Bad
"data.name" type STRING means "holiday name"

Quick reference

// Single object response
responseFields(*responseCommonFieldsSubsection()),
dataResponseFields("id" type NUMBER means "ID")

// Array response
responseFields(*responseArrayCommonFieldsSubsection()),
dataResponseFields("id" type NUMBER means "ID")

// String response (DELETE, etc.)
responseFields(*responseStringCommonFields())

// Request fields
requestFields(*fields("name" type STRING means "이름"))

// Path parameters
pathParameters(parameterWithName("id").description("ID"))

Build

# Generate HTML docs (test -> snippets -> HTML)
./gradlew clean :modules:docs:docs

# Run a specific test only
./gradlew test --tests "io.glory.commonapiapp.docs.HolidayControllerDocsTest"

Summary checklist

• Extend RestDocsSupport
• Mock the Facade (not Service)
• Use DocsFieldType (DATE, DATETIME, ENUM, etc.)
• Use Field DSL: type, means infix functions
• Write field descriptions in Korean
• Use pageRequestFormat() and pageCommonFormat() for pagination responses
• Use clear English test method names
• Mark optional fields with isOptional true

Source: gykk16/spring-skeleton — distributed by TomeVault.