7/18 (월) [Spring MVC] API 문서화

 

 

 

 

 

❑ API 문서화

 

 

➤ API 문서화란?

 

API 문서화란 클라이언트가 REST API 백엔드 애플리케이션에 요청을 전송하기 위해서 알아야 되는 요청 정보(요청 URL 또는 URI, request body, query parameter 등)를 문서로 잘 정리하는 것을 의미한다.

 

 

▶️ API 요청을 위해 필요한 정보를 문서로 정리해야 하는 이유는 무엇인가?

 

백엔드에서 만든 REST API 기반의 애플리케이션을 클라이언트 쪽에서 사용하려면 API 사용을 위한 정보가 필요하기 때문이다.

 

API 사용을 위한 정보가 담겨 있는 문서를 API 문서 또는 API 스펙(사양, Specification)이라고 한다.

 

 

▶️ API 문서를 만드는 방법

 

🥑 개발자가 수기로 작성 ➡️ 비효율적!, 기능을 빠뜨릴 수 있음!

🥑 애플리케이션 빌드를 통해 API 문서를 자동으로 생성

 

 

 

➤ Spring Rest Docs vs Swagger

 

 

▶️ Swagger의 API 문서화 방식

 

🍋 Swagger는 API 문서 자동화 오픈 소스이다.

🍋 Java 기반의 애플리케이션에서는 전통적으로 Swagger를 많이 사용해왔다.

🍋 많은 양의 애너테이션이 추가된다. ➡️ 가독성이 떨어짐

🍋 코드가 길어지면 그만큼 API 문서화를 위한 코드도 길어진다. ➡️ 유지보수성이 떨어짐

🍋 Controller 뿐만 아니라 DTO 클래스에도 애너테이션을 일일이 추가해주어야 한다.

🍋 Swagger 기반의 API 문서는 [Excute] 라는 버튼하나로 Controller에 요청을 전송할 수 있다. ➡️ API 요청 툴로서 기능을 사용할 수 있다.

 

 

▶️ Spring Rest Docs의 API 문서화 방식

 

🍑 애플리케이션 기능 구현과 관련된 코드에 API 문서 생성을 위한 애너테이션과 같은 정보를 추가하지 않는다.

🍑 Controller 테스트 클래스에 API 문서화를 위한 정보가 추가된다.

🍑 테스트 케이스의 실행결과가 “passed”로 만들지 않으면 API 문서 생성이 완료되지 않는다. ➡️ API 스펙 정보와 API 문서 정보의 불일치로 생길 수 있는 문제 방지

🍑 테스트 케이스에서 전송하는 API 문서 정보와 Controller에서 구현한 request body, response body, query parameter 등의 정보가 하나라도 일치하지 않으면 테스트 케이스 실행 결과가 “failed” 되면서 API 문서가 정상적으로 생성이 되지 않는다.

🍑 Swagger 처럼 API 호출할 수 있는 툴의 역할은 하지 못한다.

 

 

 

 

❑ Spring Rest Docs

 

 

➤ Spring Rest Docs 란?

 

Rest API 문서를 자동으로 생성해주는 Spring 하위 프로젝트이다.

 

 

➤ Spring Rest Docs 의 API 문서 생성 흐름

 

Spring Rest Docs

 

 

1. 테스트 코드 작성

🍒 슬라이스 테스트 코드 작성

🍒 API 스펙 정보(Request Body, Response Body, Query Parameter 등) 코드 작성

 

 

2. test task 실행

🍒 작성된 슬라이스 테스트 코드를 실행한다.

🍒 하나의 테스트 클래스를 실행시켜도 되지만 일반적으로 Gradle의 build task 중 하나인 test task 를 실행시켜서 API 문서 snippet(스니핏*)을 일괄 생성한다.

🍒 테스트 실행 결과가 “passed” 이면 다음 작업을 진행한다.

🍒 실행결과가 “failed” 일 경우 문제를 해결하기 위해 테스트 케이스를 수정한 뒤 다시 테스트를 진행한다.

 

※ 스니핏(snippet)

일반적으로 코드의 조각을 의미한다.

여기선 문서의 일부 조각을 의미한다.

테스트 케이스 하나당 하나의 스니핏이 생성되며, 여러개의 스니핏을 모아서 하나의 API 문서를 생성할 수 있다.

 

 

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

🍒 API 스펙 정보 코드를 기반으로 API 문서 스니핏이 .adoc 확장자를 가진 파일로 생성된다.

 

 

4. API 문서 생성

🍒 생성된 API 문서 스니핏을 모아서 하나의 API 문서로 생성한다.

 

 

5. API 문서를 HTML로 변환

🍒 생성된 API 문서를 HTML 파일로 변환한다.

🍒 HTML로 변환된 API 문서는 HTML 파일 자체를 공유해도 되고 URL을 통해 해당 HTML에 접속해서 확인할 수 있다.

 

 

 

➤ Spring Rest Docs 설정

 

1. build.gradle 설정

2. API 문서 snippet 을 사용하기 위한 템플릿 API 문서 생성

 

 

▶️ build.gradle 설정

 

API 문서를 자동으로 생성하기 위해 아래 설정 코드 추가

plugins {
	...
	id "org.asciidoctor.jvm.convert" version "3.3.2"
	...
}

...
ext {
	set('snippetsDir', file("build/generated-snippets"))
}

...
configurations {
	asciidoctorExtensions
}

dependencies {
	...
	testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
	asciidoctorExtensions 'org.springframework.restdocs:spring-restdocs-asciidoctor'
    ...
}

...
tasks.named('test') {
	outputs.dir snippetsDir
	useJUnitPlatform()
}

...
tasks.named('asciidoctor') {
	configurations "asciidoctorExtensions"
	inputs.dir snippetsDir
	dependsOn test
}

...
task copyDocument(type: Copy) {
	dependsOn asciidoctor
	from file("${asciidoctor.outputDir}")
	into file("src/main/resources/static/docs")
}

build {
	dependsOn copyDocument
}

...
bootJar {
	dependsOn copyDocument
	from ("${asciidoctor.outputDir}") {
		into 'static/docs'
	}
}

 

 

애플리케이션 실행 후 웹 브라우저에서 아래 주소로 이동하면 API 문서를 눈으로 확인할 수 있다.

http://localhost:8080/docs/index.html

 

 

 

▶️ API 문서 snippet을 사용하기 위한 템플릿(또는 source 파일) 생성

 

API 문서 스니핏이 생성 되었을 때 이 스니핏을 사용해서 최종 API 문서로 만들어 주는 템플릿 문서(index.adoc)을 생성한다.

 

아래 경로에 해당하는 디렉토리 생성 (Gradle 기반 프로젝트)

src/docs/asciidoc/

 

디렉토리 내에 비어있는 템플릿 문서를 생성 (index.adoc)

 

 

 

 

❑ Controller 테스트 케이스에 Spring Rest Docs 적용하기

 

 

➤ API 문서화를 위한 슬라이스 테스트 케이스 작성

 

Controller 슬라이스 테스트 클래스를 작성하고 API 문서화를 위한 코드를 추가해준다.

 

 

▶️ @SpringBootTest -> @WebMvcTest 로 변경

 

🍎 @WebMvcTest 는 Controller를 테스트 하기 위한 전용 애너테이션이다.

🍎 @WebMvcTest 괄호 안에 테스트 대상 Controller 클래스를 지정해준다.

 

 

▶️ @MockBean(JpaMetamodelMappingContext.class)

 

🍎 JPA에서 사용하는 Bean 들을 Mock 객체로 주입해주는 설정이다.

 

Spring Boot 기반의 테스트는 항상 최상위 패키지 경로에 있는 ~Application 클래스를 찾아서 실행한다.

~Application 클래스에 @EnableJpaAuditing 추가

➡️ JPA와 관련된 Bean을 필요로 하기 때문에 @WebMvcTest 애너테이션을 사용해서 테스트를 진행할 경우 JpaMetamodelMappingContext를 Mock 객체로 주입해주어야 한다.

 

 

▶️ 테스트 클래스 위에 @AutoConfigureRestDocs 추가

 

🍎 Spring Rest Docs 에 대한 자동 구성을 해준다.

 

 

▶️ document(..)

 

🍎 API 문서 자동 생성을 위한 API 스펙 정보 추가

🍎 .anDo(..) 메서드 : andExpect() 처럼 어떤 검증 작업을 하는 것이 아닌 일반적인 동작을 정의하고자 할 때 사용한다.

 

 

▶️ @SpringBootTest vs @WebMvcTest

 

🍓 @SpringBootTest

• @AutoConfigureMockMvc 와 함께 사용되어 Controller 를 테스트할 수 있다.
• 프로젝트에서 사용하는 전체 Bean을 ApplicationContext 에 등록하여 사용한다.
• 테스트 환경을 구성하는 것은 편리하지만 실행속도가 상대적으로 느리다.

 

🍓 @WebMvcTest

• Controller 테스트에 필요한 Bean만 ApplicationContext에 등록한다.
• 실행 속도가 상대적으로 빠르다.
• 하지만 테스트 하려는 클래스에서 의존하고 있는 객체가 있다면 해당 객체에 대해서 Mock 객체를 사용하여 의존성을 일일이 제거해주어야 한다.

 

 

 

 

 

 

감사합니다.

오개념에 대한 지적은 늘 환영입니다. 🤩