57.02_[Spring MVC] API 문서화_ Spring Rest Doc_22.11.11

>Spring Rest Docs
: Spring Rest Docs는 REST API 문서를 자동으로 생성해 주는 Spring 하위 프로젝트
: Controller(API 계층)의 슬라이스 테스트를 작성하고, 테스트가 통과되어야 API 문서가 만들어지는 것이 특징.

>Spring Rest Docs의 API 문서 생성 흐름
1. 테스트 코드 작성
1.1. 슬라이스 테스트 코드 작성
1.2. API 스펙 정보 코드 작성(문서화 코드)
2. Test Task 실행
: Gradle의 build task 실행(Gradle - build)
3. API 문서 스니핏 생성(.adoc 파일)
: 문서의 일부 혹은 조각을 의미하는 snippet(스니핏)을 생성함.
: 각각의 스니핏은 각각의 테스트 케이스와 일대일 매칭됨.
4. API 문서 생성
: 생성된 API 문서 스니핏들을 모아서 하나의 API 문서를 만든다.
5. API 문서를 HTML로 변환

>Spring Rest Docs 설정 (build.gradle 설정)
-Asciidoctor 사용 플러그인 추가 : AsciiDoc(.adoc) 문서를 생성하기 위함
-API 문서 스피닛 생성될 경로 지정
-AsciiDoctor에서 사용되는 의존 그룹 지정(asciidoctorExtensions )
-의존 라이브러리 추가(restdocs)
-의존 라이브 러리 추가(asciidoctor)
-API 문서 스피닛 생성 디렉토리 경로 설정(:test task 실행 시)
-Asciidoctor 기능을 사용을 위한 asciidoctorExtensions 설정(:asciidoctor task 실행 시)
-task copyDocument 내용 설정
-task copyDocument 사용 설정
-:bootJar task 설정
=>Spring Rest Docs 를 사용하기 위해서는 build.gradle에 많은 설정이 필요하다
=>경로 설정, Asciidoc 설정, Asciidoctor 설정

>API 문서 생성을 위한 테스트 케이스 기본 구조
-@WebMvcTest(~~~.class)
: Controller 테스트 전용 애너테이션
: 속성값으로 Controller 클래스를 넣어주면 된다.
: @SpringBootTest보다는 사실 이 애너테이션을 많이 쓰고, 앞으론 이것만 쓰면 된다.
-@MockBean(JpaMetamodelMappingContext.class)
: @WebMvcTest와 짝으로 쓰인다고 생각.
-@AutoConfigureRestDocs
: Spring Rest Docs에 대한 자동 구성
-MockMvc 필드
-@MockBean
-Test Case
-ResultActions.andDo(document( ~~));
-pathParameters
-.ignored()
-.optional()

>스피닛을 이용한 API 문서화
-API 템플릿 문서

>Asciidoc

>Asciidoc 기본 문법
-목차 구성
-박스 문단 사용
-경고 문구 추가
-URL Scheme 자동 인식
-이미지 추가

>Asciidoctor