[Spring] Snippets을 활용한 API 문서화

Snippets

• Snippets : 테스트 케이스에 API 스펙 정보를 추가하여 생성한 문서 일부의 조각 모음

  • Gradle 프로젝트에서의 템플릿 문서 디폴트 경로 : src/docs/asciidoc

  • 템플릿 문서에서의 Snippets 사용 방법 : `include::{snippets}/snippets 문서 위치 디렉토리/snippets 문서 파일명.adoc[]’

  • 템플릿 문서를 HTML파일로 변환 : [Gradle] 탭 -> :bootjat or :build 더블클릭

Asciidoc

• 🔗Asciidoc
  • Spring Rest Docs 통해 생성되는 텍스트 기반 문서 포맷
  • 기술 문서 작성을 위해 설계된 가벼운 마크업 언어

  • 🔗AsciiDoc 구문 빠른참조

  • Asciidoc 포맷 사용하여
    • 메모, 문서, 기사, 서적, E-Book, 웹 페이지, 메뉴얼 페이지, 블로그 게시물 등을 작성
    • 작성된 문서는 HTML, PDF, EPUB, 메뉴얼 페이지를 포함한 다양한 형식으로의 변환 가능

Asciidoc 기본 문법

• 🔗목차 구성

  • = API문서제목
    • 문서 제목 작성 시 =를 추가
    • = 개수에 따라 글자 크기 조정 가능 (개수 늘어날수록 글자 크기 ↓)

  • :sectnums: : 목차에 섹션 별 넘버링

  • :toc: 위치
    • 목차 위치 지정
    • ex :toc: left

  • :toclevels: 숫자 : 목차에 표시 할 제목 레벨 설정

  • :toc-title: 목차제목
    • 목차 제목 지정
    • ex :toc-title: Table of Contents
  • :source-highlighter: 소스코드하이라이터
    • 소스코드 하이라이터 지정
    • ex :source-highlighter: prettify

• 박스 문단 사용 및 경고문구

  ---

  문단 제목

       문서설명 입니다.
  

  CAUTION: 경고문구입니다. ***

  

  • API 문서에 박스문단을 구성하여 API 문서에 대한 설명 추가
  • *** 는 단락을 구분지어줌
  • 문단 제목 후 한 줄 띄우고 한칸 들여쓰기의 문단 작성 시 박스문단 사용 가능
  • CAUTION: : 경고문구
    • NOTE:, TIP:, IMPORTANT:, WARNING: 등 사용 가능

• URL Scheme 자동 인식

  • http, https, ftp, irc, mailto, hgd@gmail.com 과 같은 URL Scheme는 Asciidoc에서 자동으로 인식하여 링크 설정됨

• 이미지 추가

  • image:: : API 문서에 이미지 추가

• 문서 스니핏을 템플릿 문서에 포함

 == Controller
  === 컨트롤러
  .섹션_제목 // . 으로 하나의 스니핏 섹션 제목 표현
  include::{snippets}/post/http-request.adoc[]

• 매크로(macro)
  • Asciidoctor에서 어떠한 작업을 처리하기 위한 용어
  • 어떤 반복되는 작업을 자동화한다는 의미
• include : Asciidoctor에서 사용하는 매크로, 스니핏을 템플릿 문서에 포함 시 사용
• :: : 매크로 사용 위한 표기법
• {snippets}
  • 해당 스니핏이 생성되는 디폴트 경로
  • build.gradle 파일에 설정한 snippetsDir 변수 참조 시 사용

    // build.gradle
    ...
    ext {
     set('snippetsDir', file("build/generated-snippets"))
    }
    

Asciidoctor

• Asciidoctor

  • AsciiDoc 포맷의 문서를 파싱하여 HTML 5, 메뉴얼 페이지, PDF 및 EPUB 3 등의 문서 생성 툴
  • Spring Rest Docs에는 Asciidoc 포맷 문서 -> HTML 파일 변환을 하기 때문에 내부적으로 Asciidoctor를 사용함