blog13: Spring REST Docs2 - 요청, 응답필드

8080 포트 바꿔주기.

여러 가지 방법이 있지만 어노테이션 부착이 가장 쉽다..

@AutoConfigureRestDocs(uriScheme = "https", uriHost = "api.blog.com", uriPort = 443)

클래스 선언부 위에 달아준다.

 

@AutoConfigureRestDocs도 달아주었다.

 

@BeforeEach를 포함한 관련 초기 설정 관련 코드들을 주석처리해 주었다.

//PostControllerDocTest.java

package com.endofma.blog.controller;

import com.endofma.blog.domain.Post;
import com.endofma.blog.repository.PostRepository;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.http.MediaType;
import org.springframework.restdocs.RestDocumentationContextProvider;
import org.springframework.restdocs.RestDocumentationExtension;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.setup.MockMvcBuilders;
import org.springframework.web.context.WebApplicationContext;

import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.documentationConfiguration;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultHandlers.print;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

@SpringBootTest //부트의 경우 이걸 사용. 이 안에 SpringExtension이 포함되어 있다.
@AutoConfigureMockMvc//추가
@AutoConfigureRestDocs(uriScheme = "https", uriHost = "api.blog.com", uriPort = 443)
@ExtendWith(RestDocumentationExtension.class) //부트의 경우
//@ExtendWith({RestDocumentationExtension, SpringExtension.class}) //Spring MVC의 경우는 이렇게
public class PostControllerDocTest {
//테스트 수행 전 셋업

    @Autowired
    private MockMvc mockMvc;

    @Autowired
    private PostRepository postRepository;

//JUnit자체적으로 주입하기 때문에 생성자를 통해 주입하면 아래 에러 발생
//org.junit.jupiter.api.extension.ParameterResolutionException: No ParameterResolver registered for parameter
//public PostControllerDocTest(PostRepository postRepository){
//    this.postRepository = postRepository;
//}


    //asciidoc에 맞는 설정을 가지고 mockMvc를 설정하는 코드
//    @BeforeEach
//    void setUp(WebApplicationContext webApplicationContext, RestDocumentationContextProvider restDocumentation) {
//        this.mockMvc = MockMvcBuilders.webAppContextSetup(webApplicationContext)
//                .apply(documentationConfiguration(restDocumentation)) //덮어써짐.
//                .build();
//    }

    @Test
    @DisplayName("글 단건 조회 테스트")
    void test1() throws Exception {
        //given
        Post post = Post.builder()
                .title("제목")
                .content("내용")
                .build();
        postRepository.save(post);
        //expected
//       this.mockMvc.perform(get("/")
       this.mockMvc.perform(get("/posts/{postId}", 1L)
               .accept(MediaType.APPLICATION_JSON))
               .andDo(print())
               .andExpect(status().isOk())
               .andDo(document("index"));
    }

}

 

바꿔준 뒤 프로젝트 실행

==> genetrated-snippets -index-asciidocs 내용이 바뀜.

 

curl-request.adoc

[source,bash]
----
$ curl 'https://api.blog.com/posts/1' -i -X GET \
    -H 'Accept: application/json'
----

 

 

이제 적용하기 위해 다시 빌드하고 서버를 재실행 해보자.

내용이 바뀌었다.

 

 

요청필드 코멘트 달아주기. + 응답 필드 

 

//PostControllerDocTest.java

package com.endofma.blog.controller;

import com.endofma.blog.domain.Post;
import com.endofma.blog.repository.PostRepository;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.http.MediaType;
import org.springframework.restdocs.RestDocumentationContextProvider;
import org.springframework.restdocs.RestDocumentationExtension;
import org.springframework.restdocs.mockmvc.RestDocumentationRequestBuilders;
import org.springframework.restdocs.payload.PayloadDocumentation;
import org.springframework.restdocs.request.RequestDocumentation;
import org.springframework.test.web.servlet.MockMvc;
import org.springframework.test.web.servlet.setup.MockMvcBuilders;
import org.springframework.web.context.WebApplicationContext;

import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.documentationConfiguration;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultHandlers.print;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

@SpringBootTest //부트의 경우 이걸 사용. 이 안에 SpringExtension이 포함되어 있다.
@AutoConfigureMockMvc//추가
@AutoConfigureRestDocs(uriScheme = "https", uriHost = "api.blog.com", uriPort = 443)
@ExtendWith(RestDocumentationExtension.class) //부트의 경우
//@ExtendWith({RestDocumentationExtension, SpringExtension.class}) //Spring MVC의 경우는 이렇게
public class PostControllerDocTest {
//테스트 수행 전 셋업

    @Autowired
    private MockMvc mockMvc;

    @Autowired
    private PostRepository postRepository;

//JUnit자체적으로 주입하기 때문에 생성자를 통해 주입하면 아래 에러 발생
//org.junit.jupiter.api.extension.ParameterResolutionException: No ParameterResolver registered for parameter
//public PostControllerDocTest(PostRepository postRepository){
//    this.postRepository = postRepository;
//}


    //asciidoc에 맞는 설정을 가지고 mockMvc를 설정하는 코드
//    @BeforeEach
//    void setUp(WebApplicationContext webApplicationContext, RestDocumentationContextProvider restDocumentation) {
//        this.mockMvc = MockMvcBuilders.webAppContextSetup(webApplicationContext)
//                .apply(documentationConfiguration(restDocumentation)) //덮어써짐.
//                .build();
//    }

    @Test
    @DisplayName("글 단건 조회 테스트")
    void test1() throws Exception {
        //given
        Post post = Post.builder()
                .title("제목")
                .content("내용")
                .build();
        postRepository.save(post);
        //expected
//       this.mockMvc.perform(get("/")
//       this.mockMvc.perform(get("/posts/{postId}", 1L)
        this.mockMvc.perform(RestDocumentationRequestBuilders.get("/posts/{postId}", 1L)
                        .accept(MediaType.APPLICATION_JSON))
                .andDo(print())
                .andExpect(status().isOk())
                .andDo(document("index",
                        RequestDocumentation.pathParameters( //PathParameter를 사용할 거면 ResDocumentationRequestBuilder 사용 권함
                                RequestDocumentation.parameterWithName("postId").description("게시글 ID")
                                //path-parameter
                        ),
                        PayloadDocumentation.responseFields(
                                PayloadDocumentation.fieldWithPath("id").description("게시글 ID"),
                                PayloadDocumentation.fieldWithPath("title").description("제목"),
                                PayloadDocumentation.fieldWithPath("content").description("내용")
				//response-fields
                        )
                ));
    }

}

 

테스트 돌린 뒤 gradle - documentation - asciidoctor

 

path-parameter.adoc과 response-fields.adoc을 index.adoc에 포함시켜 준다.

path-parameters.adoc

response-fields.adoc

 

index.adoc에 추가

// index.adoc
//{snippetes}: /build/generated-snippets

= 블로그 API
:toc:

== 글 단건 조회

=== 요청
include::{snippets}/index/http-request.adoc[]

=== 요청 파라미터
include::{snippets}/index/path-parameters.adoc[]


=== 응답

include::{snippets}/index/http-response.adoc[]

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

=== curl
include::{snippets}/index/curl-request.adoc[]
// include::{snippets}/index/httpie-request.adoc[]
// include::{snippets}/index/request-body.adoc[]
// include::{snippets}/index/response-body.adoc[]

 

 

 

 

글 등록 테스트 및 글 등록 API를 index.adoc에 추가

 

먼저 테스트를 작성해 준다.

 

//PostControllerDocTest.java

package com.endofma.blog.controller;

@SpringBootTest //부트의 경우 이걸 사용. 이 안에 SpringExtension이 포함되어 있다.
@AutoConfigureMockMvc//추가
@AutoConfigureRestDocs(uriScheme = "https", uriHost = "api.blog.com", uriPort = 443)
@ExtendWith(RestDocumentationExtension.class) //부트의 경우
//@ExtendWith({RestDocumentationExtension, SpringExtension.class}) //Spring MVC의 경우는 이렇게
public class PostControllerDocTest {
//테스트 수행 전 셋업

    @Autowired
    private MockMvc mockMvc;

    @Autowired
    private PostRepository postRepository;

    @Autowired
    private ObjectMapper objectMapper;

//...

    @Test
    @DisplayName("글 등록 테스트")
    void test2() throws Exception {

        PostCreate request = PostCreate.builder()
                .title("Spring Rest Docs test title") //제목에 바보 포함 불가
                .content("부림동")
                .build();
        String json = objectMapper.writeValueAsString(request);

        this.mockMvc.perform(RestDocumentationRequestBuilders.post("/posts")
                        .contentType(MediaType.APPLICATION_JSON)
                        .accept(MediaType.APPLICATION_JSON)
                        .content(json)) //objectMapper로 변환한 json
                .andDo(print())
                .andExpect(status().isOk())
                .andDo(document("index",
                        PayloadDocumentation.requestFields(
                                PayloadDocumentation.fieldWithPath("title").description("제목"),
                                PayloadDocumentation.fieldWithPath("content").description("내용")
                        )

                ));
    }

}

 

테스트 성공하면 request-fields.adoc이 생성된다.

index.adoc에 집어 넣는다.

// index.adoc
//{snippetes}: /build/generated-snippets

= 블로그 API
:toc:

== 글 단건 조회

=== 요청
include::{snippets}/index/http-request.adoc[]

include::{snippets}/index/path-parameters.adoc[]

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

=== 응답

include::{snippets}/index/http-response.adoc[]

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

=== curl
include::{snippets}/index/curl-request.adoc[]
// include::{snippets}/index/httpie-request.adoc[]
// include::{snippets}/index/request-body.adoc[]
// include::{snippets}/index/response-body.adoc[]

 

그리고 나서 

asciidoctor 실행

 

그리고 서버 재기동