오늘
- API 문서화
API 문서화
설정
:build task 실행 전에 실행되는 task. :copyDocument task가 수행되면 index.html 파일이 src/main/resources/static/docs 에 copy 되며, copy된 index.html 파일은 API 문서를 파일 형태로 외부에 제공하기 위한 용도로 사용할 수 있다.
첫번째 줄
:asciidoctor task가 실행된 후에 task가 실행 되도록 의존성을 설정.
두번째 줄
"build/docs/asciidoc/" 경로에 생성되는 index.html을 copy한 다음,
세번째
"src/main/resources/static/docs" 경로로 index.html을 추가해 준다.
이건 index.html 을 애플리케이션 실행 파일인 jar 파일에 포함해서 웹 브라우저에서 API 문서를 확인하기 위한 용도.
위에 copy하는 index.html 은 외부에 제공하기 위한 용도,
이건 웹 브라우저에서 API 문서를 확인하기 위한 용도.
스니핏 이용해 API 문서 만들기
템플릿 문서 내용 추가
= 커피 주문 애플리케이션 은 API 문서 제목.
Hwang ~ 8번 라인은 API 문서를 생성한 사람의 정보
아까 위에서 만든 테스트 케이스 실행을 통해 생성된 API 문서 스니핏을 사용하는 부분.
템플릿 문서에서 스니핏을 사용하는 방법
include::{snippets}/스니핏 문서가 위치한 디렉토리/스니핏 문서파일명.adoc[]
HTML 파일로 변환
build 클릭
성공하면
프로젝트 부분에 파일 생성된다.
애플리케이션을 실행하고, URL을 웹 브라우저에 입력하면
Spring Rest Docs 기반 API 문서 완성!
Spring Rest Docs 에서의 Asciidoc
Asciidoc?
Spring Rest Docs를 통해 생성되는 텍스트 기반 문서 포맷이다.
Asciidoc 포맷을 사용해서 메모, 문서, 기사, 서적, E-Book, 웹 페이지, 메뉴얼 페이지, 블로그 게시물 등을 작성 할 수 있다.
Asciidoc 포맷으로 작성한 문서는 HTML, PDF, EPUB, 메뉴얼 페이지를 포함한 다양한 형식으로 변환 될 수 있다.
주로 기술 문서 작성을 위해 설계된 가벼운 마크업 언어이기도 하다.
= : 제목을 작성하기 위해 추가. === 과 같이 = 이 늘어날 수록 글자는 작아진다.
:sectnums: : 목차에서 각 섹션에 넘버링을 해주기 위해 추가.
:toc: : 목차를 문서의 어느 위치에 구성할 것인지 설정.
:toclevels: : 목차에 표시할 제목의 level을 지정할 수 있다. 위 예제에서는 4이기 때문에 =====까지의 제목만 목차에 표시된다.
:toc-title: : 목차의 제목을 설정할 수 있다.
:source-highlighter: : 문서에 표시되는 소스 코드 하일라이터를 지정한다.
박스 문단 사용하기
*** 단락을 구분 지을 수 있는 수평선을 추가할 수 있다.
문단의 제목 다음에 한 라인을 띄우고 한 칸 들여쓰기의 문단을 작성하면 박스 문단을 사용 할 수 있다.
CAUTION: 을 사용하면 경고 문구를 추가 할 수 있다.
이 외에도 NOTE: , TIP: , IMPORTANT: , WARNING: 등을 사용 할 수 있다.
NOTE: 와 TIP: 만 사용해보았다.
