🌈 [Section3] 12. [ Spring MVC ] API 문서화

📕 오늘 배운 내용!

• API 문서화
• Swagger vs Spring Rest Docs
• Spring Rest Docs
• Asciidoc

---

✏️ API 문서화 (Documentation)

• 클라이언트가 REST API 백엔드 애플리케이션에 요청을 전송하기 위해서 알아야 되는 요청 정보를 문서로 잘 정리하는 것
  ( 클라이언트 쪽에서 이 애플리케이션 사용을 위해 요청 URL / request body / query parameter 등이 필요 )

• 개발자가 직접 수기로 작성할 수도 있고, 애플리케이션 빌드를 통해 API 문서를 자동으로 생성할 수도 있음
  ( But, 수기로 작성하는 것은 아주 비효율적 ➜ API 문서 자동화 사용)

✔️ REST API

• HTTP 프로토콜을 통해 API를 설계하기 위한 아키텍처 스타일
• CRUD 기능 가짐
  [참고] https://appmaster.io/ko/blog/rest-apiran-mueosimyeo-dareun-yuhyeonggwa-eoddeohge-dareungayo

✔ API 문서 생성의 자동화가 필요한 이유

➜ 수기로 작성했을 때 시간도 많이 들고 에러 발생 가능성이 높아 비효율적이기 때문에 자동화 사용

---

✏️ Swagger vs Spring Rest Docs

✔ Swagger의 API 문서화 방식

( Swagger라는 API 문서 자동화 오픈 소스 사용한 방식 )

• 애터네이션 기반의 API 문서화 방식
  ( 애플리케이션 코드에 문서화를 위한 많은 애너테이션들이 포함됨 )

• 가독성 및 유지 보수성이 떨어짐

• API 문서와 API 코드 간의 정보 불일치 문제 발생 가능
  ( 애너테이션 내에 API 스펙 정보를 문자열로 입력하는 경우가 많기 때문 )

• API 툴로써의 기능 활용 가능
  ( API 문서 내에서 Execute 버튼을 눌러 Controller에 요청 가능 )

[참고] https://swagger.io/docs/specification/about/

✔ Spring Rest Docs의 API 문서화 방식

• 테스트 코드 기반의 API 문서화 방식

• 애플리케이션 코드에 문서화를 위한 정보들이 포함되지 않음

• 테스트 케이스의 실행이 꼭 passed여야 API 문서가 생성됨
  ➜ 애플리케이션에 정의되어 있는 API 스펙 정보와 API 문서 정보의 불일치로 인해 발생하는 문제를 방지 가능

• 테스트 케이스를 반드시 작성해야함

• API 툴로써의 기능은 제공하지 않음

---

✏️ Spring Rest Docs

• REST API 문서를 자동으로 생성해 주는 Spring 하위 프로젝트

• Controller의 슬라이스 테스트를 통해 테스트가 통과 되어야지만 API 문서가 정상적으로 만들어 짐

[참고]
https://intellij-asciidoc-plugin.ahus1.de/docs/users-guide/features/advanced/spring-rest-docs.html
https://docs.spring.io/spring-restdocs/docs/current/reference/html5/#introduction

Spring Rest Docs의 API 문서 생성 흐름

1. 테스트 코드 작성

   • 슬라이스 테스트 코드 작성
   • API 스펙 정보 코드 작성

2. 테스트 태스크 (test task) 실행

   • 작성된 슬라이스 테스트 코드를 실행
     ➜ 일반적으로 Gradle의 빌드 태스크(task)중 하나인 test task를 실행 시켜서 API 문서 스니핏(snippet)을 일괄 생성

   • 테스트 결과가 passed면 다음 작업 / failed면 테스트 케이스 수정 후 다시 실행

3. API 문서 스니핏(.adoc 파일) 생성

   • 테스트 결과가 passed면 테스트 코드의 API 스펙 정보 코드를 기반으로 API 문서 스니핏이 .adoc 확장자를 가진 파일로 생성됨
     ⠀

     ✔️ 스니핏 (snippet)

     • 문서의 일부 조각을 의미
     • 테스트 케이스 하나 당 하나의 스니핏이 생성
     • 여러개의 스니핏을 모아서 하나의 API 문서 생성 가능

4. API 문서 생성

   • 생성된 API 문서 스니핏을 모아 하나의 API 문서로 생성

5. API 문서를 HTML로 변환

   • 생성된 API 문서를 HTML 파일로 변환

   • HTML로 변환된 문서는 HTML 파일 자체를 공유할 수도 있고, URL을 통해 해당 HTML에 접속해서 확인할 수 있음

✔ Spring Rest Docs 설정

1. build.gradle에 아래와같이 설정해주어야 Spring Rest Docs가 API 문서 생성 작업을 정상적으로 수행 가능

plugins {
	id 'org.springframework.boot' version '2.7.1'
	id 'io.spring.dependency-management' version '1.0.11.RELEASE'
	id "org.asciidoctor.jvm.convert" version "3.3.2"
    // (1) .adoc 파일 확장자를 가지는 AsciiDoc 문서를 생성해주는 Asciidoctor 사용하기 위한 플러그인 추가
	id 'java'
}

group = 'com.codestates'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '11'

repositories {
	mavenCentral()
}

// (2) ext 변수의 set() 메서드를 이용해서, API 문서 스니핏이 생성될 경로 지정
ext {
	set('snippetsDir', file("build/generated-snippets"))
}

// (3) AsciiDoctor에서 사용되는 의존 그룹 지정
// (:asciidoctor task가 실행되면 내부적으로 아래에서 지정한 ‘asciidoctorExtensions’라는 그룹을 지정)
configurations {
	asciidoctorExtensions
}

dependencies {
       // (4) spring-restdocs-core / spring-restdocs-mockmvc 의존 라이브러리가 추가
	testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
  
  // (5) spring-restdocs-asciidoctor 의존 라이브러리 추가
  // ((3)에서 지정한 asciidoctorExtensions 그룹에 의존 라이브러리가 포함됩)
	asciidoctorExtensions 'org.springframework.restdocs:spring-restdocs-asciidoctor'

	implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
	implementation 'org.springframework.boot:spring-boot-starter-validation'
	implementation 'org.springframework.boot:spring-boot-starter-web'
	compileOnly 'org.projectlombok:lombok'
	runtimeOnly 'com.h2database:h2'
	annotationProcessor 'org.projectlombok:lombok'
	testImplementation 'org.springframework.boot:spring-boot-starter-test'
	implementation 'org.mapstruct:mapstruct:1.5.1.Final'
	annotationProcessor 'org.mapstruct:mapstruct-processor:1.5.1.Final'
	implementation 'org.springframework.boot:spring-boot-starter-mail'

	implementation 'com.google.code.gson:gson'
}

// (6) test task 실행 시, API 문서 생성 스니핏 디렉토리 경로 설정
tasks.named('test') {
	outputs.dir snippetsDir
	useJUnitPlatform()
}

// (7)  :asciidoctor task 실행 시, Asciidoctor 기능 사용을 위해 :asciidoctor task에 asciidoctorExtensions 설정
tasks.named('asciidoctor') {
	configurations "asciidoctorExtensions"
	inputs.dir snippetsDir
	dependsOn test
}

// (8) :build task 실행 전에 실행되는 task
// :copyDocument task가 수행되면 index.html 파일이 "src/main/resources/static/docs" 에 copy됨
// copy된 index.html 파일은 API 문서를 파일 형태로 **외부에 제공하기 위한 용도**로 사용
task copyDocument(type: Copy) {
	dependsOn asciidoctor
    // (8-1) :asciidoctor task가 실행된 후에 task가 실행 되도록 의존성 설정
	from file("${asciidoctor.outputDir}")
    // (8-2) "build/docs/asciidoc/" 경로에 생성되는 index.html을 copy
	into file("src/main/resources/static/docs")
    // (8-3) "src/main/resources/static/docs" 경로로 index.html을 추가
}

build {
	dependsOn copyDocument
    // (9) :build task가 실행되기 전에 :copyDocument task가 먼저 수행 되도록 함
}

// (10) 애플리케이션 실행 파일이 생성하는 :bootJar task 설정
// ( jar 파일에 포함해서 웹 브라우저에서 API 문서를 확인하기 위한 용도 )
bootJar {
	dependsOn copyDocument
    // (10-1) :bootJar task 실행 전에 :copyDocument task가 실행 되도록 의존성 설정
	from ("${asciidoctor.outputDir}") {
    // (10-2) Asciidoctor 실행으로 생성되는 index.html 파일을 jar 파일 안에 추가
		into 'static/docs'
        // (10-3) jar 파일에 index.html을 추가해 줌으로써 웹 브라우저에서 접속(http://localhost:8080/docs/index.html) 후, API 문서를 확인 가능
	}
}

[참고] https://docs.gradle.org/current/dsl/org.gradle.api.plugins.ExtraPropertiesExtension.html

2. API 문서 스니핏을 사용하기 위한 템플릿(또는 source 파일) 생성
➜ API 문서 스니핏이 생성 되었을 때 이 스니핏을 사용해서 최종 API 문서로 만들어 주는 템플릿 문서(index.adoc)를 생성하는 것

• ✔️ Gradle 기반 프로젝트에서는 src/docs/asciidoc/ 경로에 해당하는 디렉토리 생성하기

• ✔️ src/docs/asciidoc/ 디렉토리 내에 비어있는 템플릿 문서(index.adoc) 생성하기
  ( 나중에 만들어진 스니핏들을 한번에 모아 html로 변환할 최종 API 문서를 작성할 용도 !)

❗ 위와 같이 두가지 설정을 마치면 Controller를 테스트 할 테스트 케이스를 작성하고, 해당 Controller에 대한 API 스펙 정보를 테스트 케이스에 추가해 주면 API 문서 스니핏을 생성할 수 있다!

✔ API 문서 생성을 위한 테스트 케이스 기본 구조

@WebMvcTest(MemberController.class) // (1)
@MockBean(JpaMetamodelMappingContext.class) // (2)
@AutoConfigureRestDocs // (3)
public class MemberControllerRestDocsTest {
    @Autowired
    private MockMvc mockMvc; // (4)

    @MockBean
	  // (5) 테스트 대상 Controller 클래스가 의존하는 객체를 Mock Bean 객체로 주입 받기

    @Test
    public void postMemberTest() throws Exception {
        // given
        // (6) 테스트 데이터 

        // (7) Mock 객체를 이용한 Stubbing

        // when
        ResultActions actions =
                mockMvc.perform(
                     // (8) request 전송
                );

        // then
        actions
                .andExpect( // (9) response에 대한 기대 값 검증
                .andDo(document(
                            // (10) API 문서 스펙 정보 추가
                 ));
    }
}

( 위에서 나머지는 Mockito를 사용하여 Cotroller 슬라이스 테스트를 한 코드와 같음 )

( 클래스 레벨에 애너테이션과 then 부분에서 .andDo(document(...)); 이후가 API 문서에 대한 정보임 ! )

• (1) @WebMvcTest(MemberController.class)

  • Controller 테스트를 위한 전용 애너테이션
    ( @SpringBootTest 애너테이션 사용 X )

  • 괄호 안에는 테스트 대상 Controller 클래스 지정

• (2) @MockBean(JpaMetamodelMappingContext.class)

  • JPA에서 사용하는 Bean 들을 Mock 객체로 주입해주는 설정

    Spring Boot 기반 테스트는 항상 최상위 패키지 경로의 ~~~Application 클래스를 찾아서 실행하는데, 이 클래스에는 @EnableJpaAuditing 애너테이션이 추가되어있음

    @EnableJpaAuditing // 여기
    @SpringBootApplication
    public class Section3Week3RestDocsApplication {
    	public static void main(String[] args) {
    		SpringApplication.run(Section3Week3RestDocsApplication.class, args);
    	}
    }

    ➜ 그러면 JPA와 관련된 Bean들을 필요로 하기 때문에
    @WebMvcTest 애너테이션을 사용하여 테스트를 진행할 경우,
    괄호에 JpaMetamodelMappingContext를 Mock 객체로 주입해 주어야 함

• (3) @AutoConfigureRestDocs

  • Spring Rest Docs에 대한 자동 구성을 위한 애너테이션

• (10) API 문서를 자동 생성하기 위한 해당 Controller 핸들러 메서드의 API 스펙 정보를 document(…)에 추가

  • .andDo(…) 메서드
    ➜ API 문서를 생성 하기 위해 Spring Rest Docs에서 지원하는 메서드

  • document(…) 메서드
    ➜ 일반적인 동작을 정의하고자 할 때 사용
    ( andExpect()처럼 어떤 검증 작업을 하는 것 X )

    ➜ API 스펙 정보를 전달 받아서 실질적인 문서화 작업을 수행하는 RestDocumentationResultHandler 클래스에서 가장 핵심 기능을 하는 메서드

    [document() 메서드 안에 쓸 수 있는 파라미터들 참고]
    https://docs.spring.io/spring-restdocs/docs/current/reference/html5/#documenting-your-api
    ⠀
    [jsonFieldType 참고]
    https://docs.spring.io/spring-restdocs/docs/current/reference/html5/#documenting-your-api-request-response-payloads-fields-json-field-types

❗ 위 기본 구조를 따라 API 스펙 정보를 작성하면됨 !
( 자세한 내용은 실습 파일 참고 )

✔️ @SpringBootTest vs @WebMvcTest
⠀

• @SpringBootTest 애너테이션
  • @AutoConfigureMockMvc와 함께 사용
  • 프로젝트에서 사용하는 전체 Bean을 ApplicationContext에 등록하여 사용
    ➜ 테스트 환경을 구성하는 것은 편리
    ➜ But, 실행 속도가 상대적으로 느림
    ⠀
    👉 데이터베이스까지 요청 프로세스가 이어지는 통합 테스트에 주로 사용
    ⠀
• @WebMvcTest 애너테이션
  • Controller 테스트에 필요한 Bean만 ApplicationContext에 등록하여 사용
    ➜ 실행 속도 상대적으로 빠름
    But, Controller에서 의존하고 있는 객체가 있다면 해당 객체에 대해서 Mock 객체를 사용하여 의존성을 일일이 제거해 주어야함
    ⠀
    👉 Controller를 위한 슬라이스 테스트에 주로 사용

---

✏️ Asciidoc

• Spring Rest Docs를 통해 생성되는 텍스트 기반 문서 포맷
  ➜ Spring Rest Docs를 통해 만들어지는 문서 스니핏과 이 문서 스니핏을 사용하는 템플릿 문서는 Asciidoc 포맷의 문서로 이루어져 있음

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

• 이를 이용해 좀 더 세련되고 가독성 좋은 문서 만들기 가능 !

✔ Asciidoc 기본 문법

Ex.

= 커피 주문 애플리케이션 // (1) 문서의 제목
:sectnums: // (2)
:toc: left // (3)
:toclevels: 4 // (4)
:toc-title: Table of Contents // (5)
:source-highlighter: prettify // (6)
⠀
Joo Hyun Ju <57wnguswn57@gmail.com> // (7) 문서를 생성한 이의 정보
⠀
v1.0.0, 2022.11.15 // (8) 생성 날짜
⠀
// (9) API 문서 스니핏을 이용하는 부분
*** // (10)
== MemberController
=== 회원 등록
.curl-request // (9-1)
include::{snippets}/post-member/curl-request.adoc[] // (9-2)
⠀
.http-request
include::{snippets}/post-member/http-request.adoc[]
⠀
.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) 문서의 제목

  • =를 추가하여 제목 작성
    ( =의 개수가 늘어날 수록 글자는 작아짐 )

• (2) :sectnums:

  • 목차에서 각 섹션에 넘버링

• (3) :toc:

  • 목차를 문서의 어느 위치에 구성할 것인지 설정
    ( 위의 예시에서는 left로 설정 )

• (4) :toclevels:

  • 목차에 표시할 제목의 level 지정
    ( 위의 예시에서는 4로 지정 ➜ ==== 까지의 제목만 목차에 표시됨 )

• (5) :toc-title:

  • 목차의 제목 지정

• (6) :source-highlighter:

  • 문서에 표시되는 소스 코드 하일라이터를 지정
    ( 위의 예시에서는 prettify 지정 )

• (9) API 문서 스니핏을 이용하는 부분

  • (9-1) .

    • 하나의 스니핏 섹션 제목을 표현하기 위해 사용
      ( 위의 예시에서는 curl-request를 섹션 제목으로 함 )

  • (9-2) 템플릿 문서에서 스니핏을 사용하는 방법
    ➜ include::{snippets}/스니핏 문서가 위치한 디렉토리/스니핏 문서파일명.adoc[]

    • include
      ➜ Asciidoctor에서 사용한느 매크로(macro) 중 하나
      ➜ 스니핏을 템플릿 문서에 포함할 때 사용

    • ::
      ➜ 매크로를 사용하기 위한 표기법

      ✔️ 매크로 (macro)
      ➜ 어떤 반복되는 작업을 자동화한다는 의미

    • {snippets}
      ➜ 해당 스니핏이 생성되는 디폴트 경로
      ➜ build.gradle 파일에 설정한 snippetsDir 변수를 참조하는 데 사용할 수 있음

• (10) ***

  • 단락을 구분 지을 수 있는 수평선 추가

• 박스 문단

  • 제목 다음에 한 라인을 띄우고 한 칸 들여쓰기의 문단을 작성하면 해당 문단을 박스로 만들 수 있음

• CAUTION: / NOTE: / TIP: / IMPORTANT: / WARNING: 등

  • 경고 문구 추가

• URL Scheme 자동 인식

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

• image::

  • 이미지 추가
    Ex. image::https://spring.io/images/spring-logo-9146a4d3298760c2e7e49595184e1975.svg[spring]

[Asciidoctor 사용법 참고]

• https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#ex-normal
• https://docs.asciidoctor.org/asciidoc/latest/toc/
• https://docs.spring.io/spring-restdocs/docs/current/reference/html5/#working-with-asciidoctor

✔ Asciidoctor

• AsciiDoc 포맷의 문서를 파싱해서 HTML 5, 매뉴얼 페이지, PDF 및 EPUB 3 등의 문서를 생성하는 툴

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

---

😜 실습

• projects - be-template-api-documentation
• git - be-homework-api-documentation

위의 기본 구조에 따라 API 스펙 정보를 작성한 후 테스트가 passed가 되면,
아래와 같이 build > generated-snippets > 스니핏명 폴더에 해당 스니핏들이 생성됨 !

✔️ snippet 종류

• curl-request.adoc
  ➜ 호출에 대한 curl 명령을 포함 하는 문서
• httpie-request.adoc
  ➜ 호출에 대한 http 명령을 포함 하는 문서
• http-request.adoc
  ➜ http 요청 정보 문서
• http-response.adoc
  ➜ http 응답 정보 문서
• request-body.adoc
  ➜ 전송된 http 요청 본문 문서
• response-body.adoc
  ➜ 반환된 http 응답 본문 문서
• request-parameters.adoc
  ➜ 호출에 parameter 에 대한 문서
• path-parameters.adoc
  ➜ http 요청시 url 에 포함되는 path parameter 에 대한 문서
• request-fields.adoc
  ➜ http 요청 object 에 대한 문서
• response-fields.adoc
  ➜ http 응답 object 에 대한 문서

모든 테스트를 마치고 스니핏들이 모두 생성되면,
Spring Rest Docs 설정에서 만들어 두었던 템플릿 문서를 작성할 src/docs/asciidoc/index.adoc 파일에
아래와 같이 스니핏들을 모두 합쳐 HTML로 변환을 위한 최종 API 문서를 만들어주면 됨!

이제 다 작성을 했다면,

위 사진처럼 Gradle의 :build or :bootJar task 명령을 실행하여 index.adoc 파일을 index.html 파일로 변환하기 !

그러면 위와 같이 src/main/resources/static.docs/ 경로에 index.html이 생김 !!

이를 인터넷에서 확인하고 싶다면,

intellij 에서 애플리케이션 실행 후, http://localhost:8080/docs/index.html 이 URL을 웹 브라우저에 입력한다면

아래와 같이 API 문서가 html화 된 것을 볼 수 있음 ~

[참고] https://jogeum.net/16

---

🌈 느낀점

오늘 학습은 전에 학습했던 Controller 슬라이스 테스트에 좀 더 추가만 하면 되는 부분이어서 쉬웠고 자동으로 만들어진 API 문서를 직접 볼 수 있어서 더 재미있는 챕터였다 !