[Spring MVC] API 문서화

API 문서

클라이언트가 REST API 백엔드 애플리케이션에 요청을 전송하기 위해 필요한 정보 문서화 ( 요청 URI, Parameter 등등 )

• API 사용을 위한 정보가 담긴 문서를 API 문서 or API 스펙이라 불림 
• Swagger
  • 장점
    • 애너테이션 기반의 API 문서화 방식
    • Postman처럼 API툴로써 기능을 사용 가능 (대표적)
  • 단점
    
    • 애너테이션이 기존 코드에 더해지면서 가독성 및 유지보수성이 떨어짐
    • API문서와 API코드 간의 정보 불일치 문제 발생할 수 있음
• Spring Rest Docs
  • 장점
    • 테스트 코드 기반의 API 문서화 방식
    • 애플리케이션 기능 구현 관련코드에 API문서 생성을 위한 코딩이 필요 없음
      
      • 애플리케이션의 API 문서정보와 API의 문서 스펙이 불일치 하면 failed되면서 API문서가 생성 안됨 (테스트 결과가 passed 되야 API문서 생성  가능)
  • 단점
    • 테스트 케이스를 작성해야 하고 모든 테스트를 passed 요구됨 
    • API 툴 기능 없음

 

Spring Rest Docs

• 스프링의 하위 프로젝트
• 생성 흐름
  1. 슬라이스 테스트 코드 작성 (controller에 슬라이스 테스트 코드 작성)
  2. API 스펙 정보 코드 작성 (controller에 정의된 API 스펙정보 Request / Response Body, Query Parameter 코드)
  3. Test 실행 (gradle 빌드 테스크에서 test task를 실행시켜 스니핏 일괄 생성)
     • failed -> 스펙 불일치로 API문서 생성 x
     • passed -> 다음단계로
  4. API 문서 스니핏 생성 (.adoc) (테스트 케이스 하나당 하나의 스니핏 생성)
  5. API 문서 생성 (.adoc) (스니핏을 모아서 
  6. API 문서 -> HTML로 변환

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. 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 실행시 내부적으로 아래 그룹으로 지정된다. 
configurations {
	asciidoctorExtensions
}

dependencies {
       // 4. spring-restdocs-core, spring-restdocs-mockmvc 의존 라이브러리 추가
	testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
  
  // 5. 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) 경로에 생성되는 index.html을 copy
	into file("src/main/resources/static/docs")   // (8-3) 경로로 index.html을 추가
}

build {
	dependsOn copyDocument  // :build task가 실행되기 전에 :copyDocument task가 먼저 수행
}

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

 

@WebMvcTest ( MemberControler.class )

• Controller 테스트 전용 애너테이션
• 괄호안에 테스트 대상 Controller 지정

@MockBean(JpaMetamodelMappingContext.class)

• JPA에서 사용하는 Bean들을 mock 객체에 주입
• Application 클래스를 찾아서 실행하는데, @EnableJpaAuditing 애너테이션 추가

@AutoConfigureRestDocs

• Spring Rest Docs에 대한 자동구성