Swagger UI (1)

Swagger란?

서버로 요청되는 URL리스트를 HTML화면으로 문자화 및 테스트를 할 수 있게 해주는 라이브러리이다.
API를 엑셀이나 가이드 문서를 통해 관리하는 방식은 지속적인 업데이트를 통해야하지만
Swagger를 이용하면 API Spec 문서를 자동화 하여 간편하게 관리 및 테스트할 수 있다는 장점이 있다.

Annotation

@ApiOperation
:: 해당 컨트롤러 내부에 설명을 추가할 수 있다.

	@ApiOperation(value = "Replies POST", notes = "POST 방식의 댓글 등록")
    @PostMapping(value = "/", consumes = MediaType.APPLICATION_JSON_VALUE)
    public ResponseEntity<Map<String, Long>> register(@RequestBody ReplyDTO replyDTO){
        log.info(replyDTO);
        Map<String, Long> resultMap = Map.of("rno", 11L);
        return ResponseEntity.ok(resultMap);
    }

• Swagger UI에서 알아보기 쉽게 해당 컨트롤러에 이름을 부여 (@ApiOperation())

• 또한 register()는 ReplyDTO 인자값을 이용해 파라미터를 수집하지만 @RequestBody 어노테이션을 표시하고 있다.
  이는 JSON 문자열을 ReplyDTO로 변환하기 위함이다.

• @PostMapping에는 consumes라는 속성을 사용하고 있는데 해당 메서드를 받아 소비(consume)하는 데이터가 어떤 종류인지 명시할 수 있다.
  이 경우에는 JSON타입의 데이터를 처리하는 메서드임을 명시한다.

(1)

	public class ReplyController {
    @ApiOperation(value = "Replies POST", notes = "POST 방식의 댓글 등록")
    @PostMapping(value = "/", consumes = MediaType.APPLICATION_JSON_VALUE)
    public ResponseEntity<Map<String, Long>> register(@RequestBody ReplyDTO replyDTO){
        log.info(replyDTO);
        Map<String, Long> resultMap = Map.of("rno", 111L);
        return ResponseEntity.ok(resultMap);
    }
}

(2)

	public class ReplyController {
    @ApiOperation(value = "Replies POST", notes = "POST 방식의 댓글 등록")
    @PostMapping(value = "/", consumes = MediaType.APPLICATION_JSON_VALUE)
    public Map<String, Long> register(@Valid @RequestBody ReplyDTO replyDTO, BindingResult bindingResult) throws BindException{
        log.info(replyDTO);

        if(bindingResult.hasErrors()){
            throw new BindException(bindingResult);
        }

        Map<String, Long> resultMap = new HashMap<>();
        resultMap.put("rno", 111L);

        return resultMap;
    }
}

(1) -> (2)로의 변경점

• ReplyDTO를 수집할 때 @Valid를 적용
• BindingResult를 파라미터로 추가하고 문제가 있을 때는 BindException을 throw하도록 수정
• 메서드 선언부에 BindException을 throw하도록 수정
• 메서드 리턴값에 문제가 있다면 @RestControllerAdvice가 처리할 것이므로 정상적인 결과만 리턴