[Spring]API Documentation - Spring REST Docs

 

지난 글까지 단위 테스트와 Mock 객체를 이용한 슬라이스 테스트를 코드에 적용했다.

 

2022.09.07 - [개발/Spring] - [Spring]단위 테스트(Unit Test)

2022.09.07 - [개발/Spring] - [Spring]JUnit을 이용한 비즈니스 로직 단위 테스트

2022.09.08 - [개발/Spring] - [Spring]Hamcrest를 적용한 단위 테스트

2022.09.08 - [개발/Spring] - [Spring]Slice Test - API Layer

2022.09.09 - [개발/Spring] - [Spring]Slice Test - Data Access Layer

2022.09.13 - [개발/Spring] - [Spring]테스트에 Mockito 적용

[Spring]테스트에 Mockito 적용

이번 글부터는 작성한 애플리케이션의 API를 문서화 하는 법에 대해 알아보자.

 

API Documentation

 

API 문서화는 작업의 통일성과 개발자간의 협업에 있어 반드시 필요한 작업이다.

 

API 문서(또는 API 스펙)란 쉽게 말하면 개발자가 작성한 애플리케이션의 사용설명서이기 때문인데,

 

그런 점에선 DDD에 대해 알아볼 때 등장했던 유비쿼터스 언어와도 비슷한 면이 있다.

 

2022.09.10 - [개발/Spring] - [Spring]도메인 주도 설계(Domain Driven Design, DDD)

[Spring]도메인 주도 설계(Domain Driven Design, DDD)

사용설명서라는 부분을 조금 길게 풀어서 말하자면,

 

API 문서란 클라이언트가 REST API 백엔드 앱에 요청을 전송하기 위해 알아야 하는 정보를 담은 문서라 할 수 있다.

 

여기서 정보란 요청 URI, Request Body,  Query Parameter 등을 말한다.

 

API 문서는 엑셀등을 이용해 개발자가 직접 수기로 작성하는 방법도 있고, 앱 빌드를 통해 자동 생성하는 방법도 존재한다.

 

이어지는 글에서는 API 문서 자동화에 대해 살펴본다.

 

이는 개발자의 수고와 실수 가능성을 최대한 줄이기 위함이며, 애플리케이션의 완성도를 높이기 위함이다.

 

Spring REST Docs

 

Spring REST Docs는 2015년 발표된 API 문서화 도구로서 Swagger의 한계를 극복하기 위해 태어났다.

 

공식 문서에 따르면 Spring REST Docs는 더 정확하고, 간결하고, 잘 구성된 문서를 만드는 것이 목적인데,

 

실제로 프로덕션 코드를 건드리지 않으면서도 테스트를 기반으로 신뢰도 높은 문서를 작성할 수 있게 도와준다.

 

계속해서 Spring REST Docs의 특징과 적용에 대해 알아보자.

 

Spring REST Docs Workflow

 

바로 위에도 적었듯이, Spring REST Docs의 가장 큰 특징은 테스트를 기반으로 한 문서 작성이다.

 

이는 자연스럽게 TDD와의 연결점을 유추할 수 있게 만드는데, 그림으로 표현하면 아래와 같다.

 

2022.09.13 - [개발/Spring] - [Spring]테스트 주도 개발(Test Driven Development, TDD)

[Spring]테스트 주도 개발(Test Driven Development, TDD)

위 그림은 이전 글에서 사용했던 TDD의 동작 순서를 나타낸다.

 

실패하는 테스트를 만들고 그 테스트만 극복하는 코드 작성 및 리팩터링으로 이루어진 작은 사이클을

 

반복해서 도는 모습이 표현되어 있다.

 

그렇다면 테스트를 기반으로 한 문서 작성이란 TDD와 어떤 관계를 가지고 있을까?

 

위 그림은 문서화 작업을 포함한 TDD의 동작 순서이다.

 

이처럼 문서화 과정은 TDD사이클에 자연스럽게 융화될 수 있으며

 

테스트를 기반으로 한 문서 작성이란 위처럼 테스트에 통과한 기능만 API 문서에 등록된다는 뜻이 된다.

 

계속해서 문서 생성 흐름을 문서화를 중심으로 살펴보자.

 

1. 테스트 코드 작성
   
   
   • Slice Test 코드 작성 - Spring REST Docs는 Controller의 슬라이스 테스트와 밀접한 연관이 있다.
   • API 스펙 코드 작성 - Request Body, Response Body, Query Parameter에 대한 정보를 작성한다.
2. Test Task 실행
   
   
   • Gradle의 test task를 실행시켜 API 문서 Snippet을 일괄 생성한다.
   • 여기서 Snippet이란 테스트 케이스 하나당 생성되는 문서의 퍼즐 조각을 의미한다.
   • 테스트가 성공할 때까지 테스트 코드를 수정한다.
3. Snippet(.adoc)파일 생성
   
   
   • 테스트에 성공하면 케이스에 포함된 API 스펙 정보를 기반으로 Snippet 문서가 자동으로 생성된다.
4. API 문서 생성 - Template에 Snippet을 더해 하나의 API 문서로 만들어낸다.
5. API 문서를 HTML로 변환 - 생성된 문서는 직접 공유할 수도 있고 URI를 통해 접속할 수도 있다.

 

Getting Started

 

Spring REST Docs를 사용하기 위해선 두 가지 작업이 필요하다.

 

1. build.gradle 설정
2. Template API 문서 생성

하나씩 해결해보자. 먼저 build.gradle의 설정이다.

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" // .adoc 문서를 생성해주는 Asciidoctor 플러그인 추가
	id 'java'
}

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

repositories {
	mavenCentral()
}

ext {
	set('snippetsDir', file("build/generated-snippets")) // Snippet이 생성될 경로 지정
}

configurations {
	asciidoctorExtensions // Asciidoctor 의존그룹 지정 -> :asciidoctor task 실행시 내부적으로 그룹 지정
}

dependencies {
	testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc' // 의존 라이브러리 추가
	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.2.Final'
	annotationProcessor 'org.mapstruct:mapstruct-processor:1.5.2.Final'
	implementation 'org.springframework.boot:spring-boot-starter-mail'

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

tasks.named('test') { // :test task 실행시 API문서 생성 Snippet 경로 설정
	outputs.dir snippetsDir
	useJUnitPlatform()
}

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

// :build task 실행 전에 실행되는 task. index.html 파일을 /src/main/resources/static/doc 으로 복사
// 복사된 index.html은 API 문서를 <외부에> 저장하기 위한 용도로 사용
task copyDocument(type: Copy) {
	dependsOn asciidoctor // :asciidoctor task가 실행된 후에 task가 실행되도록 의존성 설정
	from file("${asciidoctor.outputDir}") // 설정 경로에 생성되는 index.html 복사
	into file("src/main/resources/static/docs") // 해당 경로에 index.html 붙여넣기
}

build {
	dependsOn copyDocument // :build task 전에 :copyDocument task 가 먼저 실행되도록 의존성 설정
}

bootJar { // 앱 시행 파일이 생성하는 :bootJar task 설정
	dependsOn copyDocument // :bootJar task 전에 :copyDocument task 가 먼저 실행되도록 의존성 설정
	// Asciidoctor가 생성하는 index.html을 <Jar 파일 안>에 추가
	// 따라서 웹 브라우저에 접속(http://localhost:8080/docs/index.html)후 API 문서 확인 가능
	from ("${asciidoctor.outputDir}") {
		into 'static/docs'
	}
}

task copyDocument()에서 복사되는 HTML 파일은 외부에 제공하기 위한 용도이고,

 

bootjar{} 안에서는 실행 파일인. jar에 포함해 웹 브라우저에서 API 문서를 확인하기 위한 용도이다.

 

설정을 마친 후 src/docs/asciidoc/ 폴더를 만들어 비어있는 템플릿 문서(index.adoc)를 생성해주면 준비는 끝난다.