[Section3] Spring MVC - API 문서화 2

🧑🏻‍💻 TIL(Today I Learned)

---

✔️ Asciidoc, API 문서화 실습

 

💡 Asciidoc

➡️ Spring Rest Docs를 통해 생성되는 텍스트 기반 문서 포맷

➡️ 이 포맷을 사용하여 메모, 문서, 기사, E-Book, 웹 페이지, 매뉴얼 페이지, 블로그 게시물 등을 작성할 수 있으며 HTML, PDF, EPUB, 매뉴얼 페이지를 포함한 다양한 형식으로 변환될 수 있음 

➡️ 기술 문서 작성을 위해 설계된 가벼운 마크업 언어

 

🔎 Asciidoc 문법

✔️ 목차 구성

= 커피 주문 애플리케이션 
:sectnums:
:toc: left
:toclevels: 4
:toc-title: Table of Contents
:source-highlighter: prettify

Hong Gil Dong <hgd@gmail.com>

v1.0.0, 2023.07.04

(순차적으로)

1. 문서의 제목은  =  추가, 개수가 늘어날수록 글자는 작아짐
2. 목차에서 각 섹션에 넘버링을 해주기 위해서는  :sectcums:  
3. 목차를 문서의 어느 위치에 구성할 것인지 설정하는  :toc: , 어느쪽에 위치 할 것인지 지정하면 됨(위와 같이 left)
4. 목차에 표시할 제목의 level을 지정하는  :toclevels: , 4로 지정하면 ==== 까지의 제목만 목차에 표시됨
5. 목차의 제목을 지정하는  :toc-title:  
6. 문서에 표시되는 소스 코드 하이라이터를 지정하는  :source-highlighter: , 여기서는 prettify 지정

목차 결과

 

✔️ 박스 문단 사용하기 

***
API 문서개요
 이 문서는 ...
 		... 이 문서를 통해 API의 구체적인 사용법을 알 수 있습니다. 
        
***

1. 단락을 구분할 수 있는 수평선  *** 
2. 문단의 제목 다음에 한 라인을 띄우고 한 칸 들여 쓰기의 문단을 작성하면 박스 문단 사용 가능  

박스 문단 결과

 

✔️ 경고 문구 추가

***
API 문서개요
 이 문서는 ...
 		... 이 문서를 통해 API의 구체적인 사용법을 알 수 있습니다.

CAUTION: 이 문서는 학습용으로 일부 기능에 제한이 있습니다. 
        
***

•   CAUTION:  , 사용하여 경고 문구 추가가능 
• 이 외에 NOTE: , TIP: , WARNING: 등 사용 가능 

경고 문구 결과

 

✔️ URL Schema 자동 인식

→ 다음과 같은 URL Schema는 Asciidoc에서 자동으로 인식하여 링크가 설정됨

• http
• https
• ftp
• irc
• mailto
• hgd@gmail.com

 

✔️ 이미지 추가 

image::https://spring.io/images/spring-logo-9146a4d3298760c2e7e49595184e1975.svg[spring]

• image::  사용해서 추가 가능

 

🔎  Asciidoctor 란?

➡️ Asciidoctor 포맷의 문서를 파싱해서 HTML5, 메뉴얼 페이지, PDF 및 EPUB 3 등의 문서를 생성하는 툴

➡️ Spring Rest Docs에서는 Asciidoc 포맷의 문서를 HTML 파일로 변환하기 위해 내부적으로  Asciidoctor 사용하고 있음 

➡️ 어제 테스트 케이스 실행을 통해 생성된 문서 스니펫을 템플릿 문서에 포함 시킴, 이렇게 포함된 스니펫은 애플리케이션 빌드 타임에 내부적으로 Asciidoctor가 index.adoc을 index.html 로 변환 후 특정 디렉토리에 생성해줌 

 

 

✔️ 템플릿 문서에 스니펫을 포함하는 방법

***
== MemberController
=== 회원 등록
.curl-request       // (1)
include::{snippets}/post-member/http-request.adoc[]    // (2)

.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[]

...
...

1.   .curl-request  , 에서   .  은 하나의 스니펫 섹션 제목을 표현하기 위해 사용
   → curl-request 는 섹션의 제목이며 원하는 대로 수정하면 됨 
2.   include   는  Asciidoctor에서 사용하는 매크로 중 하나, 스니펫을 템플릿 문서에 포함할 때 사용 
     ::  은 매크로를 사용하기 위한 표기법 
3.   {snippets}  는 해당 스니펫이 생성되는 디폴트 경로를 의미, build.gradle 파일에 설정한 snippetDir 변수를 참조하는 데 사용 가능

Asciidoctor에서는 어떤 작업을 처리하기 위한 용어로 매크로(macro) 사용