Skip to content

RestDocs를 사용해보자

Jump to bottom
JaeHo Kong edited this page Aug 1, 2022 · 1 revision

RestDocs이란?

Spring REST Docs helps you to document RESTful services. It combines hand-written documentation written with [Asciidoctor](http://asciidoctor.org/) and auto-generated snippets produced with [Spring MVC Test](https://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle#spring-mvc-test-framework). This approach frees you from the limitations of the documentation produced by tools like [Swagger](http://swagger.io/). It helps you to produce documentation that is accurate, concise, and well-structured. This documentation then allows your users to get the information they need with a minimum of fuss.

  1. Spring REST 문서는 RESTful 서비스를 문서화하는 데 도움이 됩니다.
  2. Asciodoctor로 작성된 수기 문서와 Spring MVC Test로 제작된 자동 생성 스니펫을 결합
  3. 이러한 접근 방식을 통해 스웨거와 같은 툴에서 생성되는 문서의 제약에서 벗어날 수 있다.
  4. 프로덕션 코드와 분리하여 문서 자동화
  5. 신뢰도 높은 API

왜 사용할까?

  1. 실제 코드에 추가되는 코드가 없다.
    • 프로덕션 코드와 분리되어있기 때문에 Swagger 같이 Config 설정 코드나 어노테이션이 우리의 프로덕션 코드를 더럽힐 일이 없다.
  2. 테스트가 성공해야 문서 작성된다.
    • Spring REST Docs는 테스트가 성공하지 않으면 문서를 만들 수 없다.
    • Spring REST Docs로 문서를 만든다는 것은 API의 신뢰도를 높이고 더불어 테스트 코드의 검증을 강제로 하게 만드는 좋은 문서화 도구이다.

build.gradle 설정

환경

  • Spring Boot 2.7.1
  • Gradle 7.4.1
  • Java 11
  • Junit5

1. Plugin 추가

  • org.asciidoctor.jvm.convert

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

    gradle 7부터 org.asciidoctor.convert가 아닌 org.asciidoctor.jvm.convert를 사용해야 한다.

    • adoc 파일 변환
    • build 디렉도리에 복사

2. 스니펙 디렉토리 설정

스니펫 : 문서의 조각

RestDocs에 대한 명세내역을 코드에 작성한 후 테스트 케이스가 정상적으로 실행이 되었다면 RestDocs의 내용을 기준으로 Snippet 문서가 생성되는데, Gradle 기준으로 build/generated-snippets 디렉토리 하위에 생성된다

image

ext{
	set('snippetsDir', file("build/generated-snippets"))
}
  • ext : 전역변수 설정
  • gradle의 스니펫은 build/generated-snippets에 생성된다. 스니펫 생성 디렉토리를 snippetsDir라는 전역변수에 담는다.

종류

  • curl-request.adoc : 호출에 대한 curl 명령을 포함 하는 문서
  • httpie-request.adoc : 호출에 대한 http 명령을 포함 하는 문서
  • http-request.adoc : http 요청 정보 문서
  • http-response.adoc : http 응답 정보 문서
  • request-body.adoc : 전송된 http 요청 본문 문서
  • response-body.adoc : 반환된 http 응답 본문 문서
  • request-parameters.adoc : 호출에 parameter 에 대한 문서
  • path-parameters.adoc : http 요청시 url 에 포함되는 path - parameter 에 대한 문서
  • request-fields.adoc : http 요청 object 에 대한 문서
  • response-fields.adoc : http 응답 object 에 대한 문서

3. asciidoctor

asciidoctor : 스니펫을 이용하여 HTML을 생성하는 도구.

  • 기존에 존재하는 docs를 삭제
  • 문서옮기기 build/docs/asciidoc → src/main/resources/static 
configurations {
	asciidoctorExtensions
}

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

asciidoctor.doFirst {
	delete file('src/main/resources/static/docs')
}

4. copyDocument

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

5. bootJar

  • bootJar 실행시 생성되도록 변경
bootJar {
    dependsOn createDocument
    from("${asciidoctor.outputDir}") {
        into 'static/docs'
    }
}

6. 의존성추가

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

진행과정

image 테스트 코드를 실행한다.

  1. 테스트 코드가 성공하면 스니펫이 생성된다.
  2. asciidoctor가 생성된 스니펫을 사용하여 문서를 작성한다.
  3. 2번 문서를 기반으로 HTML 문서가 생성된다.
  4. HTML문서를 접근가능한 main/resources/static으로 복사한다.

우리는 무엇을 해야할까?

1. 테스트코드를 통해 스니펫 생성한다.

  • MockMvc : @WebMvcTest
  • restassured : @SpringBootTest

2. asciidoctor로 HTML 문서를 만든다.

어떤 기준으로 HTML API 문서로 만들지 설정해주어야 한다. src/docs/asciidoc 하위에 adoc파일을 만든다. 네이밍은 자유이다.

예시

  • index.adoc

    = NAEPYEON(내편) Application API Document
:doctype: book
:icons: font
:source-highlighter: highlightjs
:toc: left
:toclevels: 3
:sectlinks:

include::auth.adoc[]
include::members.adoc[]
include::teams.adoc[]
include::rollingpapers.adoc[]
include::messages.adoc[]
include::errorCodes.adoc[]

  • auth.adoc

    == 로그인

=== 로그인(/api/v1/login)
operation::auth-controller-test/login[snippets='http-request,http-response']

참고

[https://velog.io/@max9106/Spring-Spring-rest-docs를-이용한-문서화](https://velog.io/@max9106/Spring-Spring-rest-docs%EB%A5%BC-%EC%9D%B4%EC%9A%A9%ED%95%9C-%EB%AC%B8%EC%84%9C%ED%99%94)

https://tecoble.techcourse.co.kr/post/2020-08-18-spring-rest-docs/

Clone this wiki locally