<div id="readability-page-1" class="page"><div>⚠️이 글은 Spring Rest Docs의 개념에 대해 정리한 글이 아닌 Spring Rest Docs를 적용하고, 발생한 문제에 대해 정리한 글입니다.
<hr>
<h2 id="️-환경">⚙️ 환경</h2>
<ul>
<li>Spring Boot 2.5.2</li>
<li>Gradle 7.0.2</li>
<li>Java 11</li>
<li>junit5</li>
<li>MocvMvc</li>
</ul>
<h2 id="️-buildgradle">⚙️ build.gradle</h2>
아래의 build.gradle에 rest docs 기능을 추가해보려고 한다.
<pre><code>plugins {
 id 'org.springframework.boot' version '2.5.2'
 id 'io.spring.dependency-management' version '1.0.11.RELEASE'
 id 'java'
}

group = 'com.example'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '11'

repositories {
 mavenCentral()
}

dependencies {
 implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
 implementation 'org.springframework.boot:spring-boot-starter-web'
 runtimeOnly 'mysql:mysql-connector-java'
 testImplementation 'org.springframework.boot:spring-boot-starter-test'
 testImplementation 'com.h2database:h2:1.4.199'
}

test {
 useJUnitPlatform()
}</code></pre>
<h3 id="plugin-추가">plugin 추가</h3>
gradle 7 부터는 <code>org.asciidoctor.convert</code>가 아닌<code>asciidoctor.jvm.convert</code>를 사용해야한다.
이 플러그인은 adoc 파일 변환, build 디렉토리에 복사하기 위한 역할을 한다.
<pre><code>plugins {
 id 'org.springframework.boot' version '2.5.2'
 id 'io.spring.dependency-management' version '1.0.11.RELEASE'
 id 'java'
 id "org.asciidoctor.jvm.convert" version "3.3.2"
}</code></pre>
<h3 id="스니펫-디렉토리-설정">스니펫 디렉토리 설정</h3>
ext는 전역변수를 설정해주는 것이다. gradle은 <code>build/generated-snippets</code>에 스니펫이 생성되므로, 스니펫 생성 디렉토리를 변수에 담아준다.
<pre><code>ext {
 snippetsDir = file('build/generated-snippets')
}
</code></pre>
<h3 id="asciidoctor-추가">asciidoctor 추가</h3>
asciidoctor 설정.
<pre><code>asciidoctor {
 dependsOn test
 inputs.dir snippetsDir
}</code></pre>
<h3 id="bootjar-추가">bootJar 추가</h3>
bootJar 설정. 스니펫을 이용해 문서 작성 후, <code>build - docs - asciidoc</code> 하위에 생기는 html 파일을 <code>resources/static/docs</code>로 복사해준다.
<pre><code>bootJar {
 dependsOn asciidoctor
 copy {
 from "${asciidoctor.outputDir}"
 into 'src/main/resources/static/docs'
 }
}</code></pre>
<h3 id="의존성-추가">의존성 추가</h3>
나는 테스트 코드를 mockMvc를 통해 작성해서 mockmvc의존성을 넣어줬다. restassured를 사용하려면 restassured 의존성을 넣어주면된다.
<pre><code>dependencies {
 // ...
 testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
}</code></pre>
<h3 id="최종-buildgradle">최종 build.gradle</h3>
<code>compileJava -&gt; test -&gt; asciidoctor -&gt; bootJar</code> 순으로 실행된다.
<pre><code>plugins {
 id 'org.springframework.boot' version '2.5.2'
 id 'io.spring.dependency-management' version '1.0.11.RELEASE'
 id 'java'
 id "org.asciidoctor.jvm.convert" version "3.3.2"
}

group = 'com.example'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '11'

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

asciidoctor {
 inputs.dir snippetsDir
 dependsOn test
}

bootJar {
 dependsOn asciidoctor
 copy {
 from "${asciidoctor.outputDir}"
 into 'src/main/resources/static/docs'
 }
}

repositories {
 mavenCentral()
}

dependencies {
 implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
 implementation 'org.springframework.boot:spring-boot-starter-web'
 runtimeOnly 'mysql:mysql-connector-java'
 testImplementation 'org.springframework.boot:spring-boot-starter-test'
 testImplementation 'com.h2database:h2:1.4.199'
 testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
}

test {
 outputs.dir snippetsDir
 useJUnitPlatform()
}
</code></pre>
<h2 id="-테스트-코드-작성">📝 테스트 코드 작성</h2>
이제 테스트 코드를 작성해주면, 통과된 테스트 코드에 따라 스니펫이 생성된다. 
나는 MockMvc를 사용했다. MockMvc의 경우 <code>@WebMvcTest</code>로 테스트가 가능하다(restassured의 경우 <code>@SpringBootTest</code>로 해야함). <code>@AutoConfigureRestDocs</code>(rest docs 관련 설정)같은 어노테이션도 붙여준다.
<pre><code>// 예시 
@ExtendWith({RestDocumentationExtension.class, SpringExtension.class})
@WebMvcTest(ReviewController.class)
@AutoConfigureRestDocs
class ReviewControllerTest {

 @Autowired
 private MockMvc mockMvc;

 @Autowired
 private ObjectMapper objectMapper;

 @Test
 @DisplayName("컨택하기")
 void newReview() throws Exception {
 String body = objectMapper.writeValueAsString(
 new ReviewCreateRequest(1, 2, "hello world", "abcdefghi", "github/kjunseo"));

 mockMvc.perform(
 post("/reviews").content(body)
 .contentType(MediaType.APPLICATION_JSON))
 .andExpect(header().string("Location", "/reviews/1"))
 .andExpect(status().isCreated())
 .andDo(document("reviews/create",
 responseHeaders(headerWithName("Location").description("review detail resource id"))
 ));
 }
}</code></pre>
이런식으로 테스트를 작성 후, 테스트가 성공하면, <code>build/generated-snippets</code> 하위에 스니펫이 생성된다.
<h2 id="-html-api문서-만들기">📝 html api문서 만들기</h2>
생성된 파일을 묶어 html api문서로 만들기 위해서 gradle인 경우 <code>src/docs/asciidoc</code> 하위에 adoc 파일을 만들어줘야한다.(네이밍은 자유!)
<img src="https://media.vlpt.us/images/max9106/post/8e49857a-424c-41b8-ac7c-417b41b06f30/%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA%202021-07-06%20%E1%84%8B%E1%85%A9%E1%84%92%E1%85%AE%2011.21.56.png">
만들어준 파일에 생성된 스니펫을 이용해서 문서를 작성하면 된다.
<pre><code>// 예시 
ifndef::snippets[]
:snippets: ./build/generated-snippets
endif::[]

== REQUEST

include::{snippets}/reviews/create/http-request.adoc[]

== RESPONSE

include::{snippets}/reviews/create/http-response.adoc[]

== REQUEST

include::{snippets}/reviews/student-search/http-request.adoc[]

== RESPONSE

include::{snippets}/reviews/student-search/http-response.adoc[]</code></pre>
그 후 <code>./gradlew build</code> 해주면 <code>resources - static - docs</code> 하위에 문서가 생긴다. 
<img src="https://media.vlpt.us/images/max9106/post/329f5887-20d9-437a-baa3-28928b82f307/%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA%202021-07-07%20%E1%84%8B%E1%85%A9%E1%84%8C%E1%85%A5%E1%86%AB%2012.28.56.png">
<h2 id="-trouble-shooting">🚀 trouble shooting</h2>
<h3 id="build-하위에-docs-디렉토리가-생기지-않는-경우"><code>build</code> 하위에 docs 디렉토리가 생기지 않는 경우</h3>
<a href="https://spring.io/guides/gs/testing-restdocs/">공식 문서</a>나 많은 블로그 글을 따라 진행해봤을때, <code>build</code> 하위에 docs 디렉토리가 생기지 않는 경우가 발생했다. 결론부터 말하면 버전 문제였다.
현재 나는 스프링 부트 2.5, gradle 7 버전을 사용하고 있는데, 이 경우에는 공식문서에 나와있는대로 진행하면 docs 디렉토리가 생기지 않는다.
gradle 7부터는 <code>id 'org.asciidoctor.convert' version '1.5.6'</code> 대신 <code>id "org.asciidoctor.jvm.convert" version "3.3.2"</code>를 사용해야한다.
<h3 id="unresolved-directive-in-apiadoc---include">Unresolved directive in api.adoc - include::</h3>
<code>src - docs - asciidoc</code> 하위의 adoc 문서에는 스니펫이 잘 적용되어도, <code>build - docs - asciidoc</code> 하위의 html에서 <code>Unresolved directive in api.adoc - include::스니펫</code> 오류가 발생했다.
생성된 스니펫 경로를 읽어오지 못해서 발생하는 문제였다.
인터넷에서는 adoc문서 상단에 아래 구문을 적어주면 된다고했으나 여전히 스니펫을 인식하지 못했다.
<pre><code>ifndef::snippets[]
:snippets: ../../../build/generated-snippets
endif::[]</code></pre>
경로를 수정하여 아래와 같이 해주니까 정상 작동했다. 아직 정확히 왜 해결된건지는 모르겠다. 😭
<pre><code>ifndef::snippets[]
:snippets: ./build/generated-snippets
endif::[]</code></pre>
<h3 id="빌드-후-최신-반영이-안되는-경우">빌드 후 최신 반영이 안되는 경우</h3>
<code>resources - static - docs</code> 하위의 html(<code>build - docs - asciidoc</code> 하위에 만들어지는 html 파일이 복사된 파일)이 build해도 최신화가 되지 않는 문제를 겪었다.
<code>resources - static - docs</code> 하위 html 파일이 뭔가 캐싱된 값이 남아있는 느낌이다.
빌드를 두 번해야 최신화가 적용되었다.
build.gradle의 bootJar 쪽 설정과 관련이 있나? 라는 생각이 들긴하지만 아직 해결하지 못했다.
<h3 id="커스텀-스니펫-적용">커스텀 스니펫 적용</h3>
커스템 스니펫을 적용하려고 찾아보다가 
<code>src/test/resources/org/springframework/restdocs/templates</code> 
하위에 .snippet 파일을 만들면 적용된다는 글을 보고 해보았으나 실패했다.
좀 더 찾아본 결과 asciidoctor라는 디렉토리를 하나 더 만들어야했다. 
<code>src/test/resources/org/springframework/restdocs/templates/asciidoctor</code>
이 하위에 스니펫 파일을 만드니까 정상 작동했다.</div></div>

air.log

⚠️이 글은 Spring Rest Docs의 개념에 대해 정리한 글이 아닌 Spring Rest Docs를 적용하고, 발생한 문제에 대해 정리한 글입니다.
⚙️ 환경
Spring Boot 2.5.2
Gradle 7.0.2
Java 11
junit5
MocvMvc
⚙️ build.gradle
아래의 build.gradle에 rest docs 기능을 추가해보려고 한다.
plugins {
    id 'org.springframework.boot' version '2.5.2'
    id 'io.spring.dependency-management' version '1.0.11.RELEASE'
    id 'java'
}
group = 'com.example'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '11'
repositories {
    mavenCentral()
}
dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    implementation 'org.springframework.boot:spring-boot-starter-web'
    runtimeOnly 'mysql:mysql-connector-java'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
    testImplementation 'com.h2database:h2:1.4.199'
}
test {
    useJUnitPlatform()
}
plugin 추가
gradle 7 부터는 org.asciidoctor.convert가 아닌asciidoctor.jvm.convert를 사용해야한다.
이 플러그인은 adoc 파일 변환, build 디렉토리에 복사하기 위한 역할을 한다.
plugins {
    id 'org.springframework.boot' version '2.5.2'
    id 'io.spring.dependency-management' version '1.0.11.RELEASE'
    id 'java'
    id "org.asciidoctor.jvm.convert" version "3.3.2"
}
스니펫 디렉토리 설정
ext는 전역변수를 설정해주는 것이다. gradle은 build/generated-snippets에 스니펫이 생성되므로, 스니펫 생성 디렉토리를 변수에 담아준다.
ext {
    snippetsDir = file('build/generated-snippets')
}
asciidoctor 추가
asciidoctor 설정.
asciidoctor {
    dependsOn test
    inputs.dir snippetsDir
}
bootJar 추가
bootJar 설정. 스니펫을 이용해 문서 작성 후, build - docs - asciidoc 하위에 생기는 html 파일을 resources/static/docs로 복사해준다.
bootJar {
    dependsOn asciidoctor
    copy {
        from "${asciidoctor.outputDir}"
        into 'src/main/resources/static/docs'
    }
}
의존성 추가
나는 테스트 코드를 mockMvc를 통해 작성해서 mockmvc의존성을 넣어줬다. restassured를 사용하려면 restassured 의존성을 넣어주면된다.
dependencies {
    // ...
    testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
}
최종 build.gradle
compileJava -> test -> asciidoctor -> bootJar 순으로 실행된다.
plugins {
    id 'org.springframework.boot' version '2.5.2'
    id 'io.spring.dependency-management' version '1.0.11.RELEASE'
    id 'java'
    id "org.asciidoctor.jvm.convert" version "3.3.2"
}
group = 'com.example'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '11'
ext {
    snippetsDir = file('build/generated-snippets')
}
asciidoctor {
    inputs.dir snippetsDir
    dependsOn test
}
bootJar {
    dependsOn asciidoctor
    copy {
        from "${asciidoctor.outputDir}"
        into 'src/main/resources/static/docs'
    }
}
repositories {
    mavenCentral()
}
dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    implementation 'org.springframework.boot:spring-boot-starter-web'
    runtimeOnly 'mysql:mysql-connector-java'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
    testImplementation 'com.h2database:h2:1.4.199'
    testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
}
test {
    outputs.dir snippetsDir
    useJUnitPlatform()
}
📝 테스트 코드 작성
이제 테스트 코드를 작성해주면, 통과된 테스트 코드에 따라 스니펫이 생성된다.
나는 MockMvc를 사용했다. MockMvc의 경우 @WebMvcTest로 테스트가 가능하다(restassured의 경우 @SpringBootTest로 해야함). @AutoConfigureRestDocs(rest docs 관련 설정)같은 어노테이션도 붙여준다.
// 예시 
@ExtendWith({RestDocumentationExtension.class, SpringExtension.class})
@WebMvcTest(ReviewController.class)
@AutoConfigureRestDocs
class ReviewControllerTest {
    @Autowired
    private MockMvc mockMvc;
    @Autowired
    private ObjectMapper objectMapper;
    @Test
    @DisplayName("컨택하기")
    void newReview() throws Exception {
        String body = objectMapper.writeValueAsString(
                new ReviewCreateRequest(1, 2, "hello world", "abcdefghi", "github/kjunseo"));
        mockMvc.perform(
                post("/reviews").content(body)
                                .contentType(MediaType.APPLICATION_JSON))
               .andExpect(header().string("Location", "/reviews/1"))
               .andExpect(status().isCreated())
               .andDo(document("reviews/create",
                       responseHeaders(headerWithName("Location").description("review detail resource id"))
               ));
    }
}
이런식으로 테스트를 작성 후, 테스트가 성공하면, build/generated-snippets 하위에 스니펫이 생성된다.
📝 html api문서 만들기
생성된 파일을 묶어 html api문서로 만들기 위해서 gradle인 경우 src/docs/asciidoc 하위에 adoc 파일을 만들어줘야한다.(네이밍은 자유!)
만들어준 파일에 생성된 스니펫을 이용해서 문서를 작성하면 된다.
// 예시 
ifndef::snippets[]
:snippets: ./build/generated-snippets
endif::[]
== REQUEST
include::{snippets}/reviews/create/http-request.adoc[]
== RESPONSE
include::{snippets}/reviews/create/http-response.adoc[]
== REQUEST
include::{snippets}/reviews/student-search/http-request.adoc[]
== RESPONSE
include::{snippets}/reviews/student-search/http-response.adoc[]
그 후 ./gradlew build 해주면 resources - static - docs 하위에 문서가 생긴다.
🚀 trouble shooting
build 하위에 docs 디렉토리가 생기지 않는 경우
공식 문서나 많은 블로그 글을 따라 진행해봤을때, build 하위에 docs 디렉토리가 생기지 않는 경우가 발생했다. 결론부터 말하면 버전 문제였다. 
현재 나는 스프링 부트 2.5, gradle 7 버전을 사용하고 있는데, 이 경우에는 공식문서에 나와있는대로 진행하면 docs 디렉토리가 생기지 않는다. 
gradle 7부터는 id 'org.asciidoctor.convert' version '1.5.6' 대신 id "org.asciidoctor.jvm.convert" version "3.3.2"를 사용해야한다.
Unresolved directive in api.adoc - include::
src - docs - asciidoc 하위의 adoc 문서에는 스니펫이 잘 적용되어도, build - docs - asciidoc 하위의 html에서 Unresolved directive in api.adoc - include::스니펫 오류가 발생했다.
생성된 스니펫 경로를 읽어오지 못해서 발생하는 문제였다.
인터넷에서는 adoc문서 상단에 아래 구문을 적어주면 된다고했으나 여전히 스니펫을 인식하지 못했다.
ifndef::snippets[]
:snippets: ../../../build/generated-snippets
endif::[]
경로를 수정하여 아래와 같이 해주니까 정상 작동했다. 아직 정확히 왜 해결된건지는 모르겠다. 😭
ifndef::snippets[]
:snippets: ./build/generated-snippets
endif::[]
빌드 후 최신 반영이 안되는 경우
resources - static - docs 하위의 html(build - docs - asciidoc 하위에 만들어지는 html 파일이 복사된 파일)이 build해도 최신화가 되지 않는 문제를 겪었다.
resources - static - docs 하위 html 파일이 뭔가 캐싱된 값이 남아있는 느낌이다.
빌드를 두 번해야 최신화가 적용되었다. 
build.gradle의 bootJar 쪽 설정과 관련이 있나? 라는 생각이 들긴하지만 아직 해결하지 못했다.
커스텀 스니펫 적용
커스템 스니펫을 적용하려고 찾아보다가
src/test/resources/org/springframework/restdocs/templates
하위에 .snippet 파일을 만들면 적용된다는 글을 보고 해보았으나 실패했다.
좀 더 찾아본 결과 asciidoctor라는 디렉토리를 하나 더 만들어야했다.
src/test/resources/org/springframework/restdocs/templates/asciidoctor
이 하위에 스니펫 파일을 만드니까 정상 작동했다.

[Spring] Spring rest docs 적용기(gradle 7.0.2)

댓글