Spring Rest Docs Custom

◎ 원하는 기능

• Spring Rest Docs를 이용하여 API 문서를 만드는데, request-parameter에 이 값이 필수적인지 아닌지의 내용을 추가하고 싶음

◎ Spring Rest Docs Custom

• Spring Rest Docs를 이용하여 자동적으로 API 문서의 일부를 만들어 주는데, 이를 일부 커스텀하여 이용할 수 있다.
• src/test/resources/org/springframework/restdocs/templates 경로에 가서 [커스텀 하고 싶은 파일].snippet 을 만들면 커스텀하여 이용 가능

◎ 예시

 @Test
 public void getUsersTest() throws Exception{
     
     ...
     
     testActions
             .andDo(getMethodDocument("get-users",
                     List.of(queryParam("page","page 번호"),
                             queryParam("size","page 크기")),
                     List.of(responseField("data", JsonFieldType.ARRAY, "결과 데이터"),
                             responseField("data[].userId", JsonFieldType.NUMBER, "회원 식별자"),
                             responseField("data[].name",JsonFieldType.STRING, "회원 이름"),
                             responseField("data[].companyLocation", JsonFieldType.STRING, "회사 위치"),
                             responseField("data[].companyName", JsonFieldType.STRING, "회사 이름"),
                             responseField("data[].companyType", JsonFieldType.STRING, "회사 타입"),
                             responseField("pageInfo.page", JsonFieldType.NUMBER, "현재 페이지"),
                             responseField("pageInfo.size", JsonFieldType.NUMBER, "현재 페이지 크기"),
                             responseField("pageInfo.totalElements", JsonFieldType.NUMBER, "총 User 수"),
                             responseField("pageInfo.totalPages", JsonFieldType.NUMBER, "총 페이지 수"))));
 }

public interface Document {
   static RestDocumentationResultHandler getMethodDocument(String identifier,
                                                           List<ParameterDescriptor> queryParameters,
                                                           List<FieldDescriptor> responseFields){
       return document(identifier,
               ApiDocumentUtils.getRequestPreProcessor(),
               ApiDocumentUtils.getResponsePreProcessor(),
               requestParameters(queryParameters),
               responseFields(responseFields));
   }

   static ParameterDescriptor queryParam(String name, String description){
       return parameterWithName(name).description(description);
   }

   static FieldDescriptor responseField(String jsonPath, JsonFieldType type, String description){
       return fieldWithPath(jsonPath).type(type).description(description);
   }
}

• Custom 이전의 get-users > request-parameters.adoc

  Parameter	Description
  page	page 번호
  size	page 크기

• src/test/resources/org/springframework/restdocs/templates
  경로에 request-parameters.snippet 추가

  • 형식은 Asciidoc 를 따름
  • File 중에 default-request-parameters.snippent을 검색(Ctrl + N)을 하여 참고하면 대략적인 형식을 알 수 있음.

   // request-parameters.snippet
    
   |===
   |Parameter|Description|필수값
  
   {{#parameters}}
   |{{#tableCellContent}}`+{{name}}+`{{/tableCellContent}}
   |{{#tableCellContent}}{{description}}{{/tableCellContent}}
   |{{#tableCellContent}}{{^optional}}true{{/optional}}{{/tableCellContent}}
  
   {{/parameters}}
   |===

• Custom 이후 get-users > request-parameters.adoc

  • 테스트를 다시 실행 후에 적용됨
    

◎ .snippet 파일을 AsciiDoc로 인식하지 않을 때 (IntelliJ)

• File > Settings > Editor > File Types
• Recognized File Types 에서 AsciiDoc files을 선택
• File name patterns에 *.snippet 추가
  

◎ 참고 자료

• Spring Rest Docs 적용 - 우아한 형제들 기술 블로그 (이호진)
• Spring REST Docs - (Son Seung Woo)