[Spring]AsciiDoc, Asciidoctor

목차

 

아스키독(AsciiDoc)은 플레인 텍스트 마크업 언어를 사용하는 사람이 읽을 수 있는 문서 포맷이다.

 

플레인 텍스트(Plain Text) - 그래픽이나 그림을 제외한 문자열

 

마크업 언어(Markup Language) - 태그 등을 이용하여 문서나 데이터의 구조를 표현하는 언어의 일종

 

사람이 읽을 수 있는(Human-Readable) - 사람이 자연스럽게 읽을 수 있는(ex. 이진 데이터 아닌) 데이터의 인코딩

 

존재하는 모든 문서편집기로 작성이 가능하면서도 자연스럽게 읽히며, HTML, PDF, Tex 등으로 쉽게 렌더링 된다.

 

공통 확장자로는 .txt와 함께 지난 글까지 알아본 .adoc이 있다.

 

또는, 마크다운 언어는 사용하기 쉬운 반면 추가 기능을 위한 다양한 구현체가 난립하는 문제가 생겼는데,

 

추가 기능 없이 조판이 가능할 정도로 다양한 문법을 처음부터 지원하며 만들어진 마크업 언어를 아스키독이라 부르기도 한다.

 

즉, 아스키독 언어를 사용해 만들어진 문서를 아스키독이라 부르는 것이다.

 

지난 글까지의 과정에서 아스키독은 커다란 지분을 차지하고 있는데,

 

조금 과장하자면 작업의 절반 이상이 아스키독에 의존하고 있음을 확인할 수 있다.

 

Spring REST Docs로 만드는 스니핏과 템플릿이 아스키독으로 이루어져 있기 때문인데,

 

이 글에선 세련된 API 문서 작성을 위한 아스키 문법의 기초를 살펴본다.

 

Index

 

= 커피 주문 애플리케이션 // 문서의 제목엔 '=' 한 개
:sectnums: // 각 섹션에 넘버링
:toc: left // 목차를 문서의 왼쪽에 표시하도록 지정
:toclevels: 4 // 목차에 표시할 제목의 Level 4로 지정. '===='까지만 표시 
:toc-title: Table of Contents // 목차의 제목
:source-highlighter: prettify // 소스코드 하이라이터

Gni <gni@gmail.com>

v1.0.0, 2022.09.15


== MemberController // '='의 개수가 늘어날수록 글자는 작아짐. 
=== 회원 등록 // '='와 제목 글자 사이에는 반드시 한 칸 이상의 공백이 필요하며,
=== 회원 정보 수정 // 제목과 본문 사이에도 한 줄 이상의 공백이 반드시 필요하다.
=== 회원 정보 조회
=== 회원 목록 조회
=== 탈퇴 회원 삭제

직관적이고 사용하기 좋은 문법을 가지고 있음을 확인할 수 있다.

 

위와 같이 작성한 문서는 HTML로 변환시 아래와 같은 모양을 나타내게 된다.

 

 

Horizontal Rule & Box Paragraph

 

''' // 단락 구분을 위한 수평선 추가
API 문서 개요 // 문단의 제목

 커피 주문 애플리케이션 API 문서 개요 // 한 줄 띄운 후 한 칸 들여쓰기로 박스 문단 생성 가능

'''

역시 간단한 문법으로 문서를 구성할 수 있다.

 

Admonitions

 

'''
API 문서 개요

 커피 주문 애플리케이션 API 문서 개요

CAUTION: 주의사항 입력 // 경고 문구 추가

'''

• CAUTION
• NOTE
• TIP
• IMPORTANT
• WARNING

등을 이용해서 다양한 경고 문구를 생성할 수 있다. 결과는 아래와 같다.

 

 

Autolinks

 

'''
API 문서 개요

 커피 주문 애플리케이션 API 문서 개요

CAUTION: 주의사항 입력

gni@gmail.com // 이메일 주소 자동 인식

https://gnidinger.tistory.com/ // https 자동 인식

'''

다양한 URL Schema를 자동 인식해서 링크가 설정된다.

 

Add an Image

 

'''
API 문서 개요

 커피 주문 애플리케이션 API 문서 개요

CAUTION: 주의사항 입력

gni@gmail.com

https://gnidinger.tistory.com/

image::https://t1.daumcdn.net/cfile/tistory/2738F84758BAC45123[spring] // 그림 추가

'''

image::와 [spring]을 이용해 이미지를 추가할 수 있다.

 

이외의 다양한 문법은 공식 사이트에 들어가면 친절하게 설명되어 있다.

 

https://docs.asciidoctor.org/

Asciidoctor Documentation Site

 

Asciidoctor

 

Asciidoctor는 AsciiDoc으로 만들어진 문서를 분석해서 HTML, PDF등 다양한 형식으로 렌더링 하는 도구이다.

 

순서도에도 나와있듯이 Spring REST Docs 역시 내부적으로 Asciidoctor를 사용해 HTML을 생성하고 있으며,

 

구체적인 문법을 모르더라도 쉽게 사용할 수 있다.

 

이 글에서는 지난 글에서 사용한, 템플릿 문서에 스니핏을 포함시키는 방법에 대해 살펴보자.

== MemberController
=== 회원 등록
.curl-request // .이후의 문자는 섹션의 제목
include::{snippets}/post-member/curl-request.adoc[] // include 사용

.http-request
include::{snippets}/post-member/http-request.adoc[]

.request-fields
include::{snippets}/post-member/request-fields.adoc[]

.http-response
include::{snippets}/post-member/http-response.adoc[]

.response-fields
include::{snippets}/post-member/response-fields.adoc[]

.curl-request와 .http-request라고 제목을 정한 대로 렌더링 된 것을 확인할 수 있다.

 

include::{snippets}/post-member/curl-request.adoc[]

 

include는 스피닛 문서를 포함시키기 위해 Asciidoctor에서 사용하는 매크로이다. 

 

'::'는 매크로를 사용하기 위한 선언이며, {snippets}는 build.gradle에 설정한 snippetsDir을 참조하는 데 사용된다.

ext {
	set('snippetsDir', file("build/generated-snippets")) // Snippet이 생성될 경로 지정
}

위 코드는 build.gradle에 추가했던 Snippet 생성 경로 지정 방법이다.