Spring REST Docs 필수값 표현하기 + Tip

아무런 설정없이 문서를 작성하면 요청 파라미터나 요청 헤더 값에 대한 설명은 작성할 수 있지만
필수값(Required) 표현이 안 되었다.

 

그 이유는 기본적으로 제공되는 스니펫 규격이 정해져있기 때문이다.

라이브러리에 포함된 기본 스니펫들

 

default-request-headers.snippet 파일

|===
|Name|Description

{{#headers}}
|{{#tableCellContent}}`+{{name}}+`{{/tableCellContent}}
|{{#tableCellContent}}{{description}}{{/tableCellContent}}

{{/headers}}
|===

스니펫들 중 하나를 선택해 읽어보면 name, descripton 속성만 있는 것을 확인할 수 있다.

 

필수값을 표현할 수 있는 방법을 알아보던 중 ..

optional() 메서드를 확인할 수 있었다.

코드를 따라가보면 optional 값을 true로 설정하는 세터 메서드다.

 

그러면 optional 사용 유무에 따라 asciidoc 문서에 어떻게 보여줄지만 고민하면 될 것 같다.

• optional() 사용 --> 필수값 X
• optional() 미사용 --> 필수값 O

 

앞에서 봤던 default-request-headers.snippet 파일을 내 입맛에 맞게 수정이 필요한데

위치는 테스트 하위 패키지에 복사 후 재정의하면 된다.

 

|===
|이름|설명|필수

{{#headers}}
|{{#tableCellContent}}`+{{name}}+`{{/tableCellContent}}
|{{#tableCellContent}}{{description}}{{/tableCellContent}}
|{{#tableCellContent}}{{#optional}}X{{/optional}}{{^optional}}**O**{{/optional}}{{/tableCellContent}}

{{/headers}}
|===

 

{{#optional}}X{{/optional}}: optional 값이 true이면 X를 표기

{{^optional}}**O**{{/optional}}: optional 값이 false이면 O를 Bold체로 표기

(머스태치 문법이라는데 구글링해서 찾았다...)

 

적용 결과

optional() 비활성화

optioanl() 활성화

요청 헤더만 설명했지만 요청 파라미터에 대한 것도 같은 방법으로 진행하면 된다.

 

 

추가 팁 

REST Docs 응답값을 보면 불필요한 헤더가 노출되는 상황이 있다.

    @BeforeEach
    public void setUp(RestDocumentationContextProvider restDocumentation) {
        RestAssured.port = port;
        spec = new RequestSpecBuilder()
                .addFilter(documentationConfiguration(restDocumentation)
                        .operationPreprocessors()
                        .withRequestDefaults(modifyHeaders().remove("Host"), prettyPrint())
                        .withResponseDefaults(modifyHeaders().remove("Date"), prettyPrint()))
                .build();
    }

이 처럼 공통 스펙에 적용하면 헤더 생략이 가능하다.

 

짠