Spring REST Docs로 API 문서 만들기

01 Feb 2022

spring

지금까지 API 문서는 주로 Swagger, Postman을 사용해서 만들었다.

API 문서를 만들면서 테스트 코드도 확인하고 로직도 다시 확인할 수 있어서
크게 불편하거나 귀찮았던 적은 없었지만 Swagger는 코드에 포함되니 그 부분이 거슬린다고 생각했었다.

마침 Spring REST Docs라는 것을 알게 되어 적용해 봤다.

Spring REST Docs 적용

gradle 설정

Asciidoctor 플러그인 적용

id 'org.asciidoctor.jvm.convert' version '3.3.2'

gradle 7 이상은 위 버전으로 설정해야 한다.

snippet 위치

ext {
    snippetsDir = file('build/generated-snippets')
}

생성된 스니펫의 출력 위치 정의

스니펫을 설정한 위치에 넣고, 문서 작성 전에 테스트 실행

asciidoctor {
    dependsOn test
    configurations 'asciidoctorExtensions'
    inputs.dir snippetsDir
    sources {
        include("**/index.adoc", "**/common/*.adoc")
    }
    baseDirFollowsSourceFile()
}

의존성 추가

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

생성된 html 파일 static 폴더로 복사

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

build {
    dependsOn copyDocument
}

Test 코드 작성 (Junit5)

restdocs/ApiDocumentUtil.java

public interface ApiDocumentUtil {
	
	static OperationRequestPreprocessor getDocumentRequest() {
		// Request Spec을 정렬해서 출력해줌
		return preprocessRequest(prettyPrint());
	}

	static OperationResponsePreprocessor getDocumentResponse() {
		// Response Spec을 정렬해서 출력해줌
		return preprocessResponse(prettyPrint());
	}

}

Test 코드 예제

.andDo(document("get-item", // 스니펫 폴더명
    ApiDocumentUtil.getDocumentRequest(), 
    ApiDocumentUtil.getDocumentResponse(),
    responseFields( // response fiels 정의, 같은 형태로 request도 정의 가능하다. 
        fieldWithPath("name").description("상품 이름"),
        fieldWithPath("price").description("가격"),
        fieldWithPath("stockQuantity").description("재고 수량"),
        fieldWithPath("createdAt").description("제품 등록 일자"),
        fieldWithPath("updatedAt").description("제품 정보 수정 일자")
    )));

html 문서 만들기

== 상품 조회 

==== /api/items/{id} (GET)

.response
include::{snippets}/get-item/response-fields.adoc[]

.test request
include::{snippets}/get-item/http-request.adoc[]

.test response
include::{snippets}/get-item/http-response.adoc[]

더 자세한 작성법은 https://narusas.github.io/2018/03/21/Asciidoc-basic.html 여기서 확인할 수 있다.

Spring REST Docs 적용

gradle 설정

Test 코드 작성 (Junit5)

참고