Spring Rest Docs - Asciidoc

Asciidoc이란?

Spring Rest Docs를 통해 생성되는 텍스트 기반의 문서 포맷이다.

(기술 문서 작성을 위해서 설계된 가벼운 마크업 언어이기도 하다)

• Asciidoc에 대해
  • https://docs.asciidoctor.org/asciidoc/latest/
  • https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#ex-normal

 

Asciidoc 목차 구성

• (1) 문서의 제목을 작성하기 위해서 =를 추가 (====와 같이 =의 개수가 늘어날 수록 글자는 작아짐)
• (2) 목차에서 각 섹션에 넘버링을 해주기 위해서 :sectnums:를 추가
• (3) :toc: 목차를 문서의 어느 위치에 구성할 것인지를 설정
• (4) :toclevels: 목차에 표시할 제목의 level을 지정 (여기서 4로 지정했기 때문에, ==== 까지의 제목만 목차에 표시)
• (5) :toc-title: 목차의 제목을 지정
• (6) :source-highlighter: 문서에 표시되는 소스 코드 highlighter를 지정
• Asciidoc의 목차 구성 방법에 대해
  • https://docs.asciidoctor.org/asciidoc/latest/toc/

 

Asciidoctor란?

AsciiDoc 포맷의 문서를 파싱해서 HTML 5, 메뉴얼 페이지, PDF, EPUB 3 등의 문서를 생성하는 툴이다.

(Spring Rest Docs에서는 Asciidoc 포맷의 문서를 HTML 파일로 변환하기 위해서, 내부적으로 사용)

매크로(Macro)
일반적으로, 어떤 반복되는 작업을 자동화한다는 의미를 가진다.
Asciidoctor에서 어떤 작업을 처리하기 위한 용어로 매크로라는 용어를 사용한다.

 

 

Asciidoc은 Spring Rest Docs를 통해서 생성되는 텍스트 기반의 문서 포맷으로,
Asciidoc을 이용해서 더 세련되고, 가독성이 좋은 API 문서를 만들 수 있다.