스프링 Rest Docs 사용법

 

 

Spring Rest Docs란?

 

Spring REST Docs는 스프링 프레임워크 기반의 프로젝트에서 API 문서를 생성하고 유지 관리하기 위한 도구입니다. 이 도구를 사용하면 API 엔드포인트 및 요청-응답 예제를 포함한 문서를 생성할 수 있습니다. Spring REST Docs는 테스트 코드와 결합하여 API의 동작을 검증하고 그 결과를 문서화하는 방식으로 작동합니다.

 

 

간단히 말하자면,   Controller 패키지를 테스트를 한뒤,   테스트가 성공했을때만  

API 문서를 작성해주는 도구다.

 

 

REST DOCS 설정:

 

 

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.1.2'
    id 'io.spring.dependency-management' version '1.1.2'
    id 'jacoco'
 
    //아스키독스 플러그인
 
    id 'org.asciidoctor.jvm.convert' version '3.3.2' //asciidoctor plugin 추가
}
 
ext{
    snippetDir = file('build/generated-snippets') //snippets 파일을 저장할 디렉토리 생성
}
 
 
asciidoctor{ //asciidoctor 설정 task
    inputs.dir snippetDir //snippets 디렉토리를 입력으로 함
    dependsOn test // test task를 의존하도록 하여, 문서 생성 전에 test를 수행하도록 함
}
 
bootJar{ //springboot를 이용한 jar 파일 생성 시 필요한 설정 task
    dependsOn asciidoctor //asciidoctor 를 의존하도록 하여, bootJar 생성 전에 asciidoctor task를 수행하도록 함
    // (jar 파일 생성 시, 문서 생성을 보장 함)
    from("build/docs/asciidoc"){ //문서 생성 시, Jar 파일 내 static/docs 에도 복사되도록 함
        into 'BOOT-INF/classes/static/docs'
    }
}
dependencies {
 
  //rest Docs
    testImplementation group: 'org.springframework.restdocs', name: 'spring-restdocs-mockmvc'
 
 
}

 

 

사용법:

 

다음과 같이 먼저  Controller 테스트를 해준다.

 

Controller 테스트가 성공하면, 

 

.andDo 메소드부터  Document를 작성하게된다.

 

Document에는

 

Doc 이름 :  documnet()

Doc 헤더 설명 :  reqeustHeaders()

Doc 파라미터 , Doc 응답필드   ...  등등

엄청 다양하게 Doc를 쓸수가있다.

 

 

 

코드를 짠 후,  테스트를 돌리고 성공시키면,

 

Build파일의   generated-snippets 속에 자동으로 doc를 작성해준다.

 

그중에 하나의 파일인 Http-Request 열어보면..

이렇게 나온다.

 

이제 해야할건 저 작은 조각들을 모아서 모아

 

하나의 보기편한 REST DOCS파일을 작성해볼것이다.

 

 

REST DOCS 파일은 여기에 저장했습니다.

 

이 REST DOCS를 

 

방금 전에 build/snipet-generated 에 자동생성된 파일들을  

include를 시켜서 모아준다.

 

참고로 DOCS 코드는 이것이다.

= REST Docs
:doctype: book
:icons: font
:source-highlighter: highlightjs
:toc: left
:toclevels: 2
:sectlinks:
 
 
ifndef::snippets[]
:snippets: ./build/generated-snippets
endif::[]
 
=== HOST Code
include::{snippets}/board/find/curl-request.adoc[]
 
=== Request Code
include::{snippets}/board/find/http-request.adoc[]
 
=== Response Code
include::{snippets}/board/find/http-response.adoc[]
 
=== Request-Header 요청에 필요한 헤더
include::{snippets}/board/find/request-headers.adoc[]
 
=== Request-PathParam 요청에 필요한 PathParam
include::{snippets}/board/find/path-parameters.adoc[]
 
=== 응답 결과
include::{snippets}/board/find/response-body.adoc[]
 
== 응답 결과 데이터 타입
include::{snippets}/board/find/response-fields.adoc[]
 

 

 

잘 모아준후, 프로그램을 돌린다면

 

이렇게 build.gradle에서 설정한 패키지에 html이 생긴다.

 

 

html을 깟을때 이렇게 예쁘게 뜬다면 성공이다!