Spring REST Docs(4) - 문서조각(snippets)

1. 문서조각을 하나의 문서로 가져오는 방법

---

= Market REST API
aaa;
:doctype: book
:icons: font
:source-highlighter: highlightjs
:toc: left
:toclevels: 4

=== 개별 문서조각 가져오는 방법
include::{snippets}/create-market/curl-request.adoc[]

== create-market
=== 여러 개의 문서조각 가져오는 방법
operation::create-market[snippets='curl-request,http-request,http-response,httpie-request,links,request-body,request-fields,request-headers,response-body,response-headers,response-fields']

결과화면

 

2. Spring REST Docs에서 만들 수 있는 문서조각

---

2.1. 기본적으로 생성되는 문서조각

 - <output-directory>/index/curl-request.adoc

 - <output-directory>/index/http-request.adoc

 - <output-directory>/index/http-response.adoc

 - <output-directory>/index/httpie-request.adoc

 - <output-directory>/index/request-body.adoc

 - <output-directory>/index/response-body.adoc

2.2. 테스트 코드에서 추가할 수 있는 문서조각

  @Test
  public void createMarketEntity() throws Exception{
    String body = FileUtils.readFileToString(new File("src/test/resources/market_1.json"));

    mockMvc.perform(post("/market/create/entity")
        .contentType(MediaType.APPLICATION_JSON)//요청 타입은 JSON이다
        .accept(MediaTypes.HAL_JSON)//HAL JSON을 돌려달라
        .content(body)
    )
        .andDo(print())
        .andExpect(status().isCreated())
        .andExpect(jsonPath("market.id").exists())//id가 있는지 확인
        .andExpect(jsonPath("_links.self").exists())
        .andExpect(jsonPath("_links.markets").exists())
        .andExpect(jsonPath("_links.update-market").exists())
        //적용한 스니펫 : links,
        .andDo(document("create-market",
              links(//링크정
                  linkWithRel("self").description("link to self"),
                  linkWithRel("markets").description("link to show all markets"),
                  linkWithRel("update-market").description("link to update a market"),
                  linkWithRel("profile").description("link to update a market")
              ),
              requestHeaders(//요청 헤더
                  headerWithName(HttpHeaders.ACCEPT).description("accept type"),
                  headerWithName(HttpHeaders.CONTENT_TYPE).description("content type")
              ),
              requestFields(//요청 필
                  fieldWithPath("marketName").description("name of new market"),
                  fieldWithPath("location").description("location of market"),
                  fieldWithPath("employees.[].name").description("name of employee of market"),
                  fieldWithPath("employees.[].age").description("name of employee of market"),
                  fieldWithPath("items.[].name").description("name of item of market"),
                  fieldWithPath("items.[].category").description("category of item of market"),
                  fieldWithPath("items.[].quantity").description("quantity of item of market")
              ),
              responseHeaders(
                  headerWithName(HttpHeaders.LOCATION).description("accept type"),
                  headerWithName(HttpHeaders.CONTENT_TYPE).description("HAL JSON type")
              ),
              //responseFields(
              relaxedResponseFields(//relaxed : 문서의 일부분만 확인해도 되게끔 설정해주는 prefix
                  //fieldWithPath : 응답의 필드를 기술하기 위한 메소드
                  //subsectioniiWithPath : 하위섹션에 대한 정보를 기술하기 위한 메소드
                  subsectionWithPath("market").description("info of market"),
                  fieldWithPath("market.id").description("id of market"),
                  fieldWithPath("market.marketName").description("name of new market"),
                  fieldWithPath("market.location").description("location of market"),
                  subsectionWithPath("market.employees[]").description("employees of market"),
                  fieldWithPath("market.employees[].id").description("id of employee of market"),
                  fieldWithPath("market.employees.[].name").description("name of employee of market"),
                  fieldWithPath("market.employees.[].age").description("name of employee of market"),
                  fieldWithPath("market.employees.[].market").description("market of employee of market"),
                  subsectionWithPath("market.items").description("items of market"),
                  fieldWithPath("market.items.[].id").description("id of item of market"),
                  fieldWithPath("market.items.[].name").description("name of item of market"),
                  fieldWithPath("market.items.[].category").description("category of item of market"),
                  fieldWithPath("market.items.[].quantity").description("quantity of item of market"),
                  fieldWithPath("market.items.[].market").description("market of item of market"),
                  fieldWithPath("_links.profile").description("profile")
              )
            )
        )
    ;
  }