Skip to content

RESTDocs 사용법

Jump to bottom
deepredk edited this page Dec 22, 2023 · 1 revision

RESTDocs 사용법

테스트 코드

result.andDo(document("user/signup",
    requestFields(
        fieldWithPath("email").type(STRING)
            .description("이메일"),
        fieldWithPath("password").type(STRING)
            .description("비밀번호")
    ),
    responseFields(
        fieldWithPath("code").ignored(),
        fieldWithPath("data.id").type(NUMBER)
            .description("가입된 회원의 id(고유 번호)"),
        fieldWithPath("data.email").type(STRING)
            .description("가입된 회원의 email")
    ))
);

위 코드가 RESTDocs에게 자동 문서화하도록 설정하는 코드입니다. (UserControllerTest의 71~85줄)

requestFields, responseFields는 말 그대로 요청 필드와 응답 필드입니다. 무슨 타입을 가지는지와 설명을 기재해주시면 됩니다.

document("user/signup") 부분은 어느 폴더에 저장되게 할지 지정하는 부분입니다. Gradle test를 실행하면 아래와 같이 자동으로 build/generated-snippets 폴더에 user/signup 하위폴더를 만들어서 snippet들을 저장합니다. image

index.adoc 파일

이걸로 끝이 아니라 아래처럼 index.adoc 파일에 include를 해주셔야 합니다.

RESTDocs가 자동으로 만들어주는건 snippet(요청 json, 응답 json 등 파편적인 정보)뿐이고 그 snippet을 조합해 문서를 만드는 건 저희의 역할인데, 그 방법이 index.adoc에 include 하는 것이기 때문입니다.

= API Documentation
:doctype: book
:icons: font
:source-highlighter: highlightjs
:toc: left
:toc-levels: 4
:sect-links:

== POST /v1/user 회원가입

=== 요청

include::{snippets}/user/signup/http-request.adoc[]

include::{snippets}/user/signup/request-fields.adoc[]

=== 응답

include::{snippets}/user/signup/response-body.adoc[]

include::{snippets}/user/signup/response-fields.adoc[]

위 코드처럼 작성하면 이런 화면이 나옵니다. image

이 index.adoc 파일은 Gradle 빌드 시 자동으로 index.html로 변환되어 src/main/resources/statis/v1/docs에 저장됩니다.

그래서 localhost:8080/v1/docs/index.html 에 접속하면 RESTDocs를 웹페이지에서 볼 수 있습니다.

snippet 파일이 만들어지는 조건 & index.adoc -> index.html 변환되는 조건

참고로 snippet 파일이 만들어지는 조건과 index.adoc가 index.html로 변환되어 static/v1/docs에 저장되는 조건이 살짝 복잡합니다.

snippet 파일은, Gradle test를 할 때만 생성됩니다. 또 index.adoc 파일이 index.html로 변환되는 것은, Gradle build 시에만 됩니다.

여기서 Gradle build를 실행하면 test를 build 전에 먼저 자동으로 하게 설정 돼있으므로 build를 하면 snippet 파일 생성과 index.adoc -> index.html 변환과 저장까지 모두 됩니다.

이걸 왜 알아야 하냐면

  • snippet 파일이 없다면 index.adoc 파일을 IDE에서 제대로 볼 수 없고 (snippet을 include 했는데 막상 해당 snippet 파일은 없으므로)
  • 통합 문서 테스트를 작성하시면 index.html 까지 갱신한 뒤에 커밋해주셔야 되기 때문입니다 (안그러면 API는 추가됐는데 RESTDocs 문서에는 반영이 안돼있을 수 있음)

즉, 정리하자면

  • index.adoc 파일을 IntelliJ에서 확인해보고 싶으시다면 Gradle test를 먼저 해주셔야 되고 (AsciiDoc 인텔리제이 플러그인깔면 볼 수 있습니다)
  • 통합 문서 테스트를 작성하실 때마다 커밋 전에 Gradle build를 먼저 해서 index.html을 갱신해주셔야 합니다
Clone this wiki locally