본문 바로가기

TIL

[Spring MVC][Spring Rest Docs]

728x90

학습 목표

  • Spring Rest Docs가 무엇인지 이해할 수 있다.

Spring Rest Docs의 API 문서 생성 흐름

  1. 테스트 코드 작성
     1).슬라이스 테스트 코드 작성
    Spring Rest Docs는 Controller의 슬라이스 테스트와 밀접한 관련이 있다. Controller에 대한 슬라이스 테스트 코드를 작성한다
    2).API 스펙 정보 코드 작성
    슬라이스 테스트 코드 다음에 Controller에 정의 되어 있는 API 스펙 정보(Response Body, Request Body , Query Parameter 등)를 코드로 작성한다
  2. test 테스크(task) 실행
    작성된 슬라이스 테스트 코드를 실행한다
    하나의 테스트 클래스를 실행시켜도 되지만 일반적으로 GRadle의 빌드 테스크(task)중 하나인 test task를 실행시켜 API 문서 스니핏을 일괄 생성한다
    테스트가 실행 결과가 "Passed"이면 다음 작업을 진행하고, "Failed"이면 문제를 해결하기 위해 테스트 케이스를 수정한 후, 다시 테스트를 진행시켜야한다.
  3. API문서 스니핏(.adoc파일)생성
    테스트 케이스의 테스트 실행결과가 "passed"이면 테스트 코드에 포함된 API 스펙정보 코드를 기반으로 API문서 스니핏이 .adoc확장자를 가진 파일로 생성된다
    스니핏은 일반적으로 코드의 일부 조각을 의미하는 경우가 많은데 여기서는 문서의 일부 조각을 의미한다.
    스니핏은 테스트 케이스 하나당 하나의 스니펫이 생성되며, 여러개의 스니핏을 모아서 하나의 API문서를 생성할 수 있다.
  4. API문서 생성
    생성된 API 문서 스니핏을 모아서 하나의 API문서로 생성한다
  5. API문서를 HTML로 변환
    생성된 API문서를 HTML 파일로 변환한다.
    HTML로 변환된 API 문서는 HTML 파일 자체를 공유할 수도 있고, URL을 통해 해당 HTML에 접속해서 확인할 수 있다

Asciidoc

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

Asciidoc 포맷을 사용해서 메모, 문서, 기사, 서적, E-Book, 웹 페이지, 메뉴얼 페이지, 블로그 게시물 등을 작성할 수 있으며 Asciidoc 포맷으로 작성된 문서는 HTML,PDF, EPUB, 메뉴얼 페이지를 포함한 다양한 형식으로 변환 될 수 있다.

또한 Asciidoc은 주로 기술 문서 작성을 위해 설계된 가벼운 마크업 언어이기도 하다.

 

Point

  • Spring Rest Docs의 API 문서 생성 흐름은 다음과 같습니다.
    • 슬라이스 테스트 코드 작성 →
    • API 스펙 정보 코드 작성 →
    • test 태스크 실행 →
    • API 문서 스니핏 생성
    • 스니핏을 포함한 API 문서 생성
    • .adoc 파일의 API 문서를 HTML로 변환
  • Spring Rest Docs를 사용해서 API 문서를 생성하기 위해서는 .adoc 문서 스니핏을 생성해주는 Asciidoctor가 필요하다.
  • HTML 파일로 변환된 API 문서는 외부에 제공할 수도 있고, 웹브라우저에 접속해서 API 문서를 확인할 수도 있다.
  • @SpringBootTest 는 데이터베이스까지 요청 프로세스가 이어지는 통합 테스트에 주로 사용되고, @WebMvcTest 는 Controller를 위한 슬라이스 테스트에 주로 사용한다.
  • document(…) 메서드는 API 스펙 정보를 전달 받아서 실질적인 문서화 작업을 수행하는 RestDocumentationResultHandler 클래스에서 가장 핵심 기능을 하는 메서드이다.
  • OperationRequestPreprocessor와 OperationResponsePreprocessor를 이용해 API 문서를 생성 전에 전처리를 수행할 수 있다.
  • requestFields(…)는 문서로 표현될 request body를 의미하며, 파라미터로 전달되는 List<FieldDescriptor> 의 원소인 FieldDescriptor 객체가 request body에 포함되는 데이터를 표현한다.
  • responseFields(…)는 문서로 표현될 response body를 의미하며, 파라미터로 전달되는 List<FieldDescriptor> 의 원소인 FieldDescriptor 객체가 response body에 포함된 데이터를 표현한다.
  • Controller 테스트를 위한 테스트 케이스 실행으로 생성된 API 문서 스니핏은 템플릿 문서에 포함해서 사용할 수 있다.
  • 애플리케이션 빌드를 통해 템플릿 문서를 HTML 파일로 변환할 수 있다.
  • 변환된 HTML 파일을 ‘src/main/resources/static/docs/’ 디렉토리에 위치 시키면 웹 브라우저로 API 문서를 확인할 수 있다.
  • Asciidoc은 Spring Rest Docs를 통해 생성되는 텍스트 기반 문서 포맷이다.
  • Asciidoc은 주로 기술 문서 작성을 위해 설계된 가벼운 마크업 언어이기도 하다.
  • Asciidoc을 이용해서 ****조금 더 세련되고, 가독성 좋은 API 문서를 만들 수 있다.
  • Asciidoctor는 AsciiDoc 포맷의 문서를 파싱해서 HTML 5, 매뉴얼 페이지, PDF 및 EPUB 3 등의 문서를 생성하는 툴이다.
728x90

'TIL' 카테고리의 다른 글

[Spring MVC] [애플리케이션 빌드/실행/배포]  (0) 2022.11.15
[Spring MVC] [Asciidoc]  (0) 2022.11.14
[Spring MVC][API 문서화]  (0) 2022.11.11
[SpringMVC][TDD]  (0) 2022.11.10
[Spring MVC][Mockito]  (0) 2022.11.10