[Spring] Rest Docs 이용해보기

RestDocs를 이용하면 API에 대한 문서를 생성할 수가 있다.

 

수행하려는 Test클래스에 @AutoConfigureRestDocs 다음과 같은 어노테이션을 사용해주면 준비는 완료된다.

        mockMvc.perform(post("/api/events/")
                    .contentType(MediaType.APPLICATION_JSON_UTF8)
                    .accept(MediaTypes.HAL_JSON)
                    .content(objectMapper.writeValueAsString(event)))
                .andDo(print())
                .andExpect(status().isCreated())
                .andExpect(jsonPath("id").exists())
                .andExpect(header().exists(HttpHeaders.LOCATION))
                .andExpect(jsonPath("free").value(false))
                .andExpect(jsonPath("offline").value(true))
                .andExpect(jsonPath("eventStatus").value(EventStatus.DRAFT.toString()))
                .andExpect(jsonPath("_links.self").exists())
                .andExpect(jsonPath("_links.query-events").exists())
                .andExpect(jsonPath("_links.update-events").exists())
                .andDo(document("create-event",
                        links(
                                linkWithRel("self").description("link to self"),
                                linkWithRel("query-events").description("link to query events"),
                                linkWithRel("update-events").description("link to update an existing event")
                        ),
                        requestHeaders(
                                headerWithName(HttpHeaders.ACCEPT).description("accept header"),
                                headerWithName(HttpHeaders.CONTENT_TYPE).description("content type header")
                        ),
                        requestFields(
                                fieldWithPath("name").description("Name of new event"),
                                fieldWithPath("description").description("description of new event"),
                                fieldWithPath("beginEnrollmentDateTime").description("date time of begin of new event"),
                                fieldWithPath("closeEnrollmentDateTime").description("date time of close of new event"),
                                fieldWithPath("beginEventDateTime").description("date time of begin of new event"),
                                fieldWithPath("endEventDateTime").description("date time of end of new event"),
                                fieldWithPath("location").description("location of new event"),
                                fieldWithPath("basePrice").description("base Price of new event"),
                                fieldWithPath("maxPrice").description("max Price of new event"),
                                fieldWithPath("limitOfEnrollment").description("limit of new event")
                        ),
                        responseHeaders(
                                headerWithName(HttpHeaders.LOCATION).description("새로 생성된 이벤트를 조회할 수 있는 URL"),
                                headerWithName(HttpHeaders.CONTENT_TYPE).description("HAL/JSON 타입")
                        ),
                        relaxedResponseFields(
                                fieldWithPath("id").description("identifier of new event"),
                                fieldWithPath("name").description("Name of new event"),
                                fieldWithPath("description").description("description of new event"),
                                fieldWithPath("beginEnrollmentDateTime").description("date time of begin of new event"),
                                fieldWithPath("closeEnrollmentDateTime").description("date time of close of new event"),
                                fieldWithPath("beginEventDateTime").description("date time of begin of new event"),
                                fieldWithPath("endEventDateTime").description("date time of end of new event"),
                                fieldWithPath("location").description("location of new event"),
                                fieldWithPath("basePrice").description("base Price of new event"),
                                fieldWithPath("maxPrice").description("max Price of new event"),
                                fieldWithPath("limitOfEnrollment").description("limit of new event"),
                                fieldWithPath("free").description("it tells if this event is free or not"),
                                fieldWithPath("offline").description("it tells if this event is offline or not"),
                                fieldWithPath("eventStatus").description("eventstatus"),
                                fieldWithPath("_links.self.href").description("link to self"),
                                fieldWithPath("_links.query-events.href").description("link to query event list"),
                                fieldWithPath("_links.update-events.href").description("link to update existing event")
                        )
                ))
                ;

15 line 부터 시작이다. 

그냥 기본세팅 doc 만 추출하기 위해서 andDo(document("create-event")) 만 하게되면

색상의 6개 파일만 생성이 된다. 파일 내용은 대략 다음과 같이 나오게 된다.

body 값이 알아보기 쉽게끔 출력이 되었는데, 이것은 따로 bean 을 custom 해준 덕분이고 설정을 하지않으면 줄바꿈이 되지 않아서 보기가 힘들다. 이를 설정하기 위해서

test 폴더 안에 RestDocsConfiguration 이라는 클래스를 따로 생성해주고 test의 configuration을 알리기 위한

@TestConfiguration을 사용하였다. 내부 코드를 다음과 같이 입력을 하면 docs들이 위에서 보았던 것 처럼 보기 편하게끔 뽑히게 된다.

 

추가적인 docs을 원한다면 코드에 나와있는대로 입력하면 된다. ResponseFields 부분을 보면 relaxed 라고 앞에 붙여져 있는데 일반적이면 모든 필드를 나열을 해야 오류가 나지 않는다. 그러나 relaxedResponseFields를 붙이면 그게 허용이 된다.