Gradle(kts) Spring REST Docs 적용

• 작성 기준, Kotlin 1.7, Gradle 7.6.1
• Spring REST Docs 사용을 위해선 Java 8 / SpringFramework 5.0.2 이상의 환경 필요

의존성 추가

• build.gradle.kts에 의존성을 추가한다.

dependencies {
  // ... spring-boot-starter-web 등등 생략

  // MockMvc Test 를 사용하는 Spring REST Docs
   testImplementation("org.springframework.restdocs:spring-restdocs-mockmvc")
}

• Spring REST Docs는 문서 작성에 AsciiDoc을 사용하므로 플러그인 추가가 필요
• AsciiDoc 플러그인 최신 버전은 여기서 확인

plugins {
	// ... 생략
	id("org.asciidoctor.jvm.convert") version "3.3.2"
}

• 스니펫 디렉토리 설정
• 스니펫의 경우, Ascii Doc 문서를 생성할 때에 사용된다.

// Ascii Doc Snippet Directory
val snippetsDir by extra { file("build/generated-snippets") }

• Build Task 작성

// Ascii Doc Create Tasks
tasks {
    // Test 결과를 snippet Directory에 출력
    test {
        outputs.dir(snippetsDir)
    }

    asciidoctor {
        // test 가 성공해야만, 아래 Task 실행
        dependsOn(test)

        // 기존에 존재하는 Docs 삭제(문서 최신화를 위해)
        doFirst {
            delete(file("src/main/resources/static/docs"))
        }

        // snippet Directory 설정
        inputs.dir(snippetsDir)

        // Ascii Doc 파일 생성
        doLast {
            copy {
                from("build/docs/asciidoc")
                into("src/main/resources/static/docs")
            }
        }
    }

    build {
        // Ascii Doc 파일 생성이 성공해야만, Build 진행
        dependsOn(asciidoctor)
    }
}

테스트 코드 작성하기

• @SpringBootTest 가 아닌, 슬라이스 테스트(WebMvcTest)를 이용해도 상관 없다. 다만 이 경우 컨트롤러에서 사용하는 Bean에 대해서 Mocking이 필요
• SampleController와 SampleService는 생성된 상태임을 가정하고 작성되었다.

@ExtendWith(RestDocumentationExtension::class)
@SpringBootTest
internal class SampleControllerTest(@Autowired var mockMvc: MockMvc) {
    @Autowired
    var sampleService: SampleService

  // AsciiDoc 생성을 위해 설정
  @BeforeEach
   fun setUp(
       webApplicationContext: WebApplicationContext,
       restDocumentationContextProvider: RestDocumentationContextProvider
   ) {
       mockMvc = MockMvcBuilders.webAppContextSetup(webApplicationContext)
           .apply<DefaultMockMvcBuilder>(
               documentationConfiguration(
                   restDocumentationContextProvider
               )
           )
           .build()
   }

 @Test
 void ASCII_DOC_문서_생성() throws Exception {
        mockMvc.perform(
            get("/sample/api/url").contentType(MediaType.APPLICATION_JSON)
                .accept(MediaType.APPLICATION_JSON)
        )
            .andExpect(status().isOk)
            .andDo(MockMvcResultHandlers.print() // Console 창에서 출력 내용 확인
            .andDo(document("sample-docs"))
    }
}

생성된 Snippets 확인

• 테스트를 실행시키면 스니펫 디렉토리로 지정했던 경로(build/generated-snippets)에 6개의 Docs문서가 생성된다.
• 불필요하다고 판단되는 스니펫의 경우는 다음 문서를 보고 수정/삭제 할 수 있다.
• http-request.adoc 파일을 열어보면, 아래처럼 지정되어 있으며, 수정을 통해 헤더값 변경이 가능하다.

[source,http,options="nowrap"]
----
GET /sample/api/url HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: localhost:8080

----

HTML 문서로 생성하기

스니펫은 최종적으로 Ascii Doc 문서로 생성해야 한다.

• Gradle을 사용중이므로, src/docs/asciidoc 폴더를 생성 후 sample.doc 를 새롭게 추가한다.

// snippet 경로를 못 읽어들이는 버그로 인해 추가
ifndef::snippets[]
:snippets: ./build/generated-snippets
endif::[]

// Ascii Doc 서식
:doctype: article
:icons: font
:source-highlighter: highlight.js
:toc: left
:toclevels: 4
:sectnums:
:sectlinks:
:sectanchors:

= Sample API

== Sample API 가져오기

* 요청
include::{snippets}/sample-docs/http-request.adoc[]
* 응답
include::{snippets}/sample-docs/http-response.adoc[]

• 그리고 다시 프로젝트 루트의 위치에서, 테스트 문서 생성 CLI를 입력

./gradlew asciidoctor

파일을 열어보면, HTML 형태로 문서가 자동 생성 되어 있다.

해당 파일을 HTML 뷰어를 이용해서 보게 되면 일반적인 웹 화면으로 볼 수 있다.

정적 파일은 src/main/ressources/static/docs 에 생성되므로 프로젝트를 실행시키면 웹 url(localhost:8080/docs/sample.html)에서도 실시간으로 확인이 가능하다.

실제로 유의미한 API Docs작성을 위해서는, Path Parameters, Request Parameters, RequestBody, Request Parts와 응답 값등을 모두 자세히 노출해주어야 한다.

관련된 내용은 Spring REST Docs에 굉장히 자세히 설명되어 있으니, 이를 통해 확인후 적용할 수 있다.

아스키독 작성법 공식문서를 확인 후, HTML 문서의 가독성을 높일 수도 있다.