[스프링 기반 REST API 개발] 3-5. 스프링 REST Docs: 링크, (Req, Res) 필드와 헤더 문서화

스프링 기반 REST API 개발

3. HATEOAS와 Self-Decribtive Message 적용

포스팅 참조 정보

GitHub

공부한 내용은 GitHub에 공부용 Organizations에 정리 하고 있습니다

해당 포스팅에 대한 내용의 GitHub 주소

실습 내용이나 자세한 소스코드는 GitHub에 있습니다
포스팅 내용은 간략하게 추린 핵심 내용만 포스팅되어 있습니다

https://github.com/freespringlecture/spring-rest-api-study/tree/chap03-05_rest_docs_snippets_create

해당 포스팅 참고 인프런 강의

https://www.inflearn.com/course/spring_rest-api/dashboard

실습 환경

• Java Version: Java 11
• SpringBoot Version: 2.1.2.RELEASE

5. 스프링 REST Docs: 링크, (Req, Res) 필드와 헤더 문서화

요청 필드 문서화

• requestFields() + fieldWithPath()
• responseFields() + fieldWithPath()
• requestHeaders() + headerWithName()
• responseHedaers() + headerWithName()
• links() + linkWithRel()

테스트 할 것

API 문서 만들기

• 요청 본문 문서화: request-body
• 응답 본문 문서화: response-body
• 링크 문서화: links
  • self
  • query-events
  • update-event
  • profile 링크 추가
• 요청 헤더 문서화: requestHeaders
• 요청 필드 문서화: requestFields
• 응답 헤더 문서화: responseHeaders
• 응답 필드 문서화: responseFields

Relaxed 접두어

Relaxed 접두어를 사용하지 않고 전부 다 문서화 하는 것을 권장

API가 변경되었을 때 변경을 테스트가 감지해서 적절하게 문서도 바뀐 API코드에 맞춰서 업데이트를 할 수 있으므로

• 장점: 문서 일부분만 테스트 할 수 있다
• 단점: 정확한 문서를 생성하지 못한다

링크, 요청(헤더, 필드), 응답(헤더, 본문) 문서화 적용

...

import static org.springframework.restdocs.headers.HeaderDocumentation.*;
import static org.springframework.restdocs.hypermedia.HypermediaDocumentation.linkWithRel;
import static org.springframework.restdocs.hypermedia.HypermediaDocumentation.links;
import static org.springframework.restdocs.payload.PayloadDocumentation.*;

...

public class EventControllerTests {

    ...

    @Test
        @TestDescription("정상적으로 이벤트를 생성하는 테스트")
        public void createEvent() throws Exception {
            mockMvc.perform(post("/api/events/")
                    .contentType(MediaType.APPLICATION_JSON_UTF8) //요청타입
                    .accept(MediaTypes.HAL_JSON) //받고싶은 타입
                    .content(objectMapper.writeValueAsString(event))) //event를 json을 String으로 맵핑

                    ...

                    .andDo(document("create-event", //문서 이름
                        links(  //링크 문서화
                                linkWithRel("self").description("link to self"),
                                linkWithRel("query-events").description("link to query events"),
                                linkWithRel("update-event").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("date time of begin 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 enrollment")
                        ),
                        responseHeaders( //응답 헤더 문서화
                                headerWithName(HttpHeaders.LOCATION).description("Location header"),
                                headerWithName(HttpHeaders.CONTENT_TYPE).description("Content type")
                        ),
                        responseFields( //응답 본문 문서화
                                fieldWithPath("id").description("identifier of new event"),
                                fieldWithPath("name").description("Name of new event"),
                                fieldWithPath("description").description("date time of begin 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 enrollment"),
                                fieldWithPath("free").description("it tells if this event is free or not"),
                                fieldWithPath("offline").description("it tells if this event is offline meeting or not"),
                                fieldWithPath("eventStatus").description("event status"),
                                fieldWithPath("_links.self.href").description("link to self"),
                                fieldWithPath("_links.query-events.href").description("link to query events list"),
                                fieldWithPath("_links.update-event.href").description("link to update an existing event")
                        )
                ))

                ...