[Asciidoctor] Spring REST Docs

언제까지 REST API 문서를 직접 작성할꺼야? 날새것다. 이제는 자동으로 API 가이드 문서를 만들어보자!

Asciidoctor

It combines hand-written documentation written with Asciidoctor and auto-generated snippets produced with Spring MVC Test. This approach frees you from the limitations of the documentation produced by tools like Swagger.(스프링 공식 문서)

 

REST Docs는 우리가 만든 애플리케이션 API 문서를 쉽게 만들수 있도록 도와주는 도구다. 스프링 공식 문서에 따르면 'Asciidoctor'를 이용하여 자동으로 REST API 문서를 만들어주는데, 무려 Spring MVC Test 코드를 기반으로 만들어진다. 즉, 내가 TDD를 통해 작성한 테스트 케이스들이 모두 문서화 되는 것이다. (Difference from Swagger)

 

AsciiDoc은 쉽게 읽고 쓸 수 있는 문서 작성 도구이면서, 동시에 DocBook, HTML 으로 변환할 수 있는 강력한 기능을 제공한다. 비록, Markdown의 사용법보다 간결함은 떨어지지만, 전문적인 문서를 작성할 수 있다는 장점이 있다.

 

Gradle을 사용한다면 간단히 설치할 수 있다.

// Spring REST Docs
asciidoctor 'org.springframework.restdocs:spring-restdocs-asciidoctor'
testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'

 

아래의 명령어를 통해 REST API 문서를 생성할 수 있다.

 ./gradlew asciidoc

생성된 문서는 build/asciidoc/html5 폴더에 HTML 파일이 생기며, 브라우져에서 이쁘게 만들어진 REST API 문서를 확인할 수 있다.

 

Asciidoctor 작성법

처음에 상당히 헤맨 부분을 적어본다. REST API HTML 파일이 build/asciidoc/html5 폴더에 생성된다고 언급했다.

그렇다면, 이 문서는 무엇을 기반으로 만들어질까?

build/generated-snippets 폴더를 살펴보면 알 수 있다. Run All tests 시, 테스트에서 작성했던 document의 식별자로 된 폴더들이 생성된다. 그 안에는 *.adoc 확장자를 가진 파일들이 만들어져 있다. 즉, Asciidoc의 index.html은 *.adoc 파일들을 include하여 작성할 수 있는 것이다.

 

$ /gradlew asciidoc 명령어를 통해 build하며, 테스트 단위별로 API스펙 명세서가 *.adoc 확장자로 개별 생성된다. *.adoc 파일을 'Snippet'이라 한다.

@Test
void sayHello() throws Exception {
	mockMvc.perform(get("/"))
		.andExpect(status().isOk())
		.andExpect(content().string(containsString("Hello, world!")))
		.andDo(document("app-say-hello"));
}

테스트 코드에 .andDo() 메서드를 사용하여 identifier("app-say-hello")를 지정하면 된다.

 

Asciidoctor 주의

주의할 점은, 빌드 혹은 컴파일 오류나 asciidoc 문서가 제대로 안 만들어질 경우 문서 생성이 되지 않는다.

단, 모든 테스트 케이스를 100% 통과해야 build 할 수 있다는 점도 기억하자.

이 경우 아래의 방법들을 시도해보자:

 

1. 빌드 혹은 컴파일 오류

아래의 설정은 ' ./gradlew asciidoc' 명령어 실행시 모든 테스트 코드들을 돌리고 나서 Success라면, 문서를 만들겠다는 설정이다. 조금 더 번거로운 확인 작업을 생략할 수 있다는 장점이 있다.

// build.gradle 맨 밑
asciidoctor {
    dependsOn test
}

2. asciidoc 문서가 제대로 안 만들어질 경우

문서가 제대로 만들어지지 않는다면, 아래의 명령어를 통해 이미 만들어진 문서를 모두 지우고 새로 생성할 수 있다.

./gradlew clean asciidoctor

 

 

[공식] Spring REST Docs

[공식] Asciidoctor Documentation

[참고] Spring REST Docs 간단히 써보기

[참고] Asciidoctor 기본 사용법

[테마] Asciidocs 테마 적용하기

[카카오 참고] https://developers.kakao.com/docs/latest/ko/kakaologin/rest-api#before-you-begin

 

Updated 2021. 6. 29