해당 글은 속닥속닥 기술블로그에 작성된 글과 동일합니다.

속닥속닥 링크

0. intro

저희 속닥속닥 팀은 기존엔 API 명세를 notion을 통해 작성했습니다.
하지만 실제 코드와 연동되지 않는 점이 불편했고, API별 테스트를 통한 검증을 하고 싶었습니다.

이에 신뢰성있는 API 문서를 프론트엔드에 공유할 수 있는 REST Docs를 사용하기로 했습니다.
다음은 REST Docs 를 세팅하고 문서화 한 과정입니다.

1. build.gradle

plugins {
   id 'org.springframework.boot' version '2.7.1'
   id 'io.spring.dependency-management' version '1.0.11.RELEASE'
   id 'java'
   id "org.asciidoctor.jvm.convert" version "3.3.2"
}

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

configurations {
   asciidoctorExtensions // dependencies 에서 적용한 것 추가
}

repositories {
   mavenCentral()
}
ext {
	// 사용할 변수 선언
   set('snippetsDir', file("build/generated-snippets"))
}

dependencies {
   implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
   implementation 'org.springframework.boot:spring-boot-starter-validation'
   implementation 'org.springframework.boot:spring-boot-starter-web'
   implementation 'org.springframework.boot:spring-boot-starter-mail'
   implementation 'com.github.ulisesbocchio:jasypt-spring-boot-starter:3.0.3'
   implementation 'com.google.guava:guava:31.0.1-jre'

		// build/generated-snippets 에 생긴 .adoc 조각들을 프로젝트 내의 .adoc 파일에서 읽어들일 수 있도록 연동
    // .adoc 파일을 HTML로 만들어 export
   asciidoctorExtensions 'org.springframework.restdocs:spring-restdocs-asciidoctor'
   compileOnly 'org.projectlombok:lombok'

   runtimeOnly 'com.h2database:h2'
   runtimeOnly 'mysql:mysql-connector-java'

   annotationProcessor 'org.projectlombok:lombok'

   testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'

   testImplementation 'org.springframework.boot:spring-boot-starter-test'
   testImplementation 'io.rest-assured:rest-assured:4.4.0'
   testImplementation 'io.rest-assured:spring-mock-mvc:4.4.0'
   testImplementation 'org.mockito:mockito-inline:3.8.0'

   implementation 'io.jsonwebtoken:jjwt-api:0.11.5'
   runtimeOnly 'io.jsonwebtoken:jjwt-impl:0.11.5'
   runtimeOnly 'io.jsonwebtoken:jjwt-jackson:0.11.5'
}

test {
   // 위에서 작성한 snippetsDir 디렉토리를 test의 output으로 구성하는 설정 
   // -> 스니펫 조각들이 build/generated-snippets로 출력
   outputs.dir snippetsDir

   // 테스트 실행
   useJUnitPlatform()
}

// asciidoctor 작업 구성
asciidoctor {
   // 위에서 작성한 configuration 적용
   configurations 'asciidoctorExtensions'
   
   // source가 없으면 .adoc파일을 전부 html로 만들어버림
   // source 지정시 특정 adoc만 HTML로 만든다.
   sources{
      include("**/index.adoc","**/common/*.adoc")
   }

   // 특정 .adoc에 다른 adoc 파일을 가져와서(include) 사용하고 싶을 경우 경로를 baseDir로 맞춰주는 설정
   // (개별 adoc으로 운영한다면 필요 없는 옵션)
   baseDirFollowsSourceFile()

   // snippetsDir 를 입력으로 구성
   inputs.dir snippetsDir

   // asciidoctor 전 test 실행!
   dependsOn test
}

// static/docs 폴더 비우기
asciidoctor.doFirst {
   delete file('src/main/resources/static/docs')
}

// asccidoctor 작업 이후 생성된 HTML 파일을 static/docs 로 copy
task createDocument(type: Copy) {
   dependsOn asciidoctor

   from file("build/docs/asciidoc")
   into file("src/main/resources/static")
}

// build 전 createDocument(REST Docs 문서화) 실행!
build {
   dependsOn createDocument
}

Gradle 7.4.1 버전

grovvy 문법을 정확히 알지 못해 틀린 부분이 있을 수 있습니다.

1-1. 빌드 과정

1. 테스트 실행
2. 테스트 결과를 build/generated-snippets에 저장
3. 이전 static/index.html 비우기
4. src/docs/asciidoc/index.adoc을 통해 build/docs/asciidoc/ 에 index.html 생성
5. 생성된 HTML 파일을 build 에서 src/main/resources/static/로 이동한다

사실 이때 index.html 이 생성되는 주기를 언제로 할지 고민했습니다.

build 단위로 재생성을 할 시 build 시간이 길어지기 때문에, test 마다 실행 시간이 길어진다는 문제가 있었습니다.

asciidoctor 명령어를 이용해 수동 export 를 하는 방안도 고려했지만, 아직 실행 시간이 길어진 정도가 크지 않아 현재 세팅을 유지하고 있습니다.

2. 테스트 코드 작성

2-1. RestAssuredMockMvc

Spring의 MockMvc 위에 빌드된 REST API인 RestAssuredMockMvc 를 사용했습니다.

RestAssured 와 문법이 같고, @WebMvcTest 형태의 테스트가 가능합니다.

편한 문법으로 빠르게 테스트하기 위해 해당 API를 사용했습니다.

관련 링크

공식문서

RestAssuredMockMvc - spring-mock-mvc 2.8.0 javadoc

baeldung

2-2. 테스트 환경 세팅 (ControllerTest)

import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.documentationConfiguration;
import static org.springframework.restdocs.operation.preprocess.Preprocessors.prettyPrint;

// ... 등록된 컨트롤러/ MockBean 임포트

import io.restassured.module.mockmvc.RestAssuredMockMvc;
import io.restassured.module.mockmvc.specification.MockMvcRequestSpecification;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.extension.ExtendWith;
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
import org.springframework.boot.test.mock.mockito.MockBean;
import org.springframework.restdocs.RestDocumentationContextProvider;
import org.springframework.restdocs.RestDocumentationExtension;
import org.springframework.test.web.servlet.setup.MockMvcBuilders;
import org.springframework.web.context.WebApplicationContext;

@WebMvcTest({
        PostController.class,
        // ... 테스트할 컨트롤러 등록
})
@ExtendWith(RestDocumentationExtension.class)
public class ControllerTest {

    protected MockMvcRequestSpecification restDocs;

    @MockBean
    protected PostService postService;
    // ... MockBean 등록

		// RestDocs 세팅
    @BeforeEach
    void setRestDocs(WebApplicationContext webApplicationContext,
                     RestDocumentationContextProvider restDocumentation) {

        restDocs = RestAssuredMockMvc.given()
                .mockMvc(MockMvcBuilders.webAppContextSetup(webApplicationContext)
                        .apply(documentationConfiguration(restDocumentation)
                                .operationPreprocessors()
                                .withRequestDefaults(prettyPrint())
                                .withResponseDefaults(prettyPrint()))
                        .build())
                .log().all();
    }
}

2-3. 테스트 작성 방식

class HashtagControllerTest extends ControllerTest { [// (0)](https://www.notion.so/REST-Docs-2f26a6e79ce045aa95a87445e2da4d38)

    @DisplayName("해시태그로 검색 시 없는 해시태그이면 404 반환")
    @Test
    void findPostsWithHashtags_Exception_NoHashtag() {
				// Mockito로 등록된 MockBean 세팅
        doThrow(new HashtagNotFoundException())
                .when(hashtagService)// [(1)](https://www.notion.so/REST-Docs-2f26a6e79ce045aa95a87445e2da4d38)
                .findPostsWithHashtag(matches("없는태그"), any());

				// 테스트 수행
        restDocs
                .contentType(MediaType.APPLICATION_JSON_VALUE)
                .when().get("/posts?hashtag=없는태그&size=5&page=0")
                .then().log().all()
                .assertThat() [// (2)](https://www.notion.so/REST-Docs-2f26a6e79ce045aa95a87445e2da4d38)
                .apply(document("search/byHashtag/fail/noHashtag")) [// (3)](https://www.notion.so/REST-Docs-2f26a6e79ce045aa95a87445e2da4d38)
                .statusCode(HttpStatus.NOT_FOUND.value());
    }

(0) 위의 ControllerTest 를 상속합니다.
(1) hashtagService는 ControllerTest 에 @MockBean으로 등록되어 있습니다.
(2) 가독성을 돕는 코드. 아래 내용들을 검증합니다.
(3) build/docs/asciidoc/ 안의 해당 디렉토리에 결과 adoc 파일들이 저장됩니다.

3. AsciiDocs 작성

3-1. adoc 조각들 생성

빌드하면 build/generated-snippets 폴더에 테스트에서 작성한 board/create/fail 디렉토리에 adoc 조각들이 생성되어 있습니다.

기본적으로 다음과 같은 조각들이 default로 생성됩니다.

• curl-request.adoc
• http-request.adoc
• httpie-request.adoc
• http-response.adoc
• request body
• response body

우리는 이 중 http-request.adoc (요청) , http-response.adoc (응답)을 사용합니다. 이외 파일들은 사용하지 않습니다.

3-2. index.adoc 문서 작성

1) 플러그인 설치

우선 adoc 파일 작성의 편의를 위해 AsciiDoc 플러그인을 설치합니다.

해당 플러그인으로 adoc 결과물을 gui 형태로 볼 수 있고, 문법 확인도 더 간편해집니다!

2) 문서 작성

이제 API 문서를 adoc 형태로 작성하면 됩니다.

src/docs/asciidoc/ 디렉토리 안에 index.adoc 파일을 만들고 문서를 작성합니다.

(노가다…)

= 속닥속닥 API 명세
:doctype: book
:icons: font
:source-highlighter: highlightjs // 코드들의 하이라이팅을 highlightjs를 사용
:toc: left // Table Of Contents(목차)를 문서의 좌측에 두기
:toclevels: 2 // 목차 레벨 설정
:sectlinks:
:sectnums: // 분류별 자동으로 숫자를 달아줌 
:docinfo: shared-head

== 메인페이지 // "="는 마크다운 "#"과 같은 기능

=== 메인페이지 조회
==== 성공
operation::board/find/content[snippets='http-request,http-response'] // 특정 adoc 파일 자동 임포트

//... 아래 부분들 직접 작성

• operation::디렉토리명[snippets=’원하는 조각들’]
  • 문서로 사용할 조각들을 명시해 자동으로 가져온다.

자세한 Asciidoc 사용법 링크

3-3. 빌드 후 index.html 생성

이제 빌드하면

위에 작성한 index.adoc 파일이 index.html 형태로 export됩니다!
index.html 파일은
build/docs/asciidoc/ , src/main/resources/static/ 두 카테고리 안에 있습니다.

( build.gradle 의 createDocument 명령어로 복사했습니다.)

이중 저희가 웹 상에 보여줄 문서는 src/main/resources/static/ 안에 위치해 있습니다.

문서 링크

1) 깃허브 push

이제 src/main/resources/static/index.html 파일을 pr을 날려
깃허브 레포에 병합합니다.

2) README.md에 링크 추가

## 속닥속닥

[RESTDocs 로 구현된 API 명세](backend/sokdak/src/main/resources/static/index.html)

README.md에 링크를 남겨주시면

다음과 같이 index.html에 접근 가능합니다.

3) github pages 설정

좀더 편하게 API 문서를 보기 위해 github pages를 이용합니다.

이때

• main 브랜치로 활성화하면 main 브랜치 속 index.html로
• dev 브랜치로 활성화하면 dev 브랜치 속 index.html로

접근 가능합니다.

현재는 dev 브랜치로 설정해두었습니다.

결과

이제 https://woowacourse-teams.github.io/2022-sokdak/ 로 들어갈 시

README.md 가 뜨고
링크를 클릭 시

언제 어디서나 해당 링크로 API 명세를 볼 수 있습니다.
개발자 뿐 아니라 유저들도 해당 API 문서에 접근 가능합니다.