[Swagger] Multi @ApiResponse에 동일 코드 사용시 나타나는 에러

안녕하세요. Swagger를 통해 Api문서를 정리하다 신기한 점을 발견하고, 이를 해결했던 방법에 대해 설명하려 합니다.

초기 코드

@ApiOperation(value = "게시글 저장")
    @ApiResponses(value = {
            @ApiResponse(code = 201, message = "저장 성공", response = PostSaveResponseDto.class),
            @ApiResponse(code = 400, message = "등록되지 않은 개인 미션", response = ErrorResponse.class),
            @ApiResponse(code = 400, message = "등록되지 않은 유저", response = ErrorResponse.class),
            @ApiResponse(code = 400, message = "하루 인증 횟수 초과", response = ErrorResponse.class)
    })

위의 코드에서는 @ApiResponses안에 선언한 @ApiResponse에서 동일한 코드 값인 400코드를 작성하고 있습니다.

HttpStatus 스펙의 기본 Error를 바탕으로 400을 반환하려 했고, 제가 개발한 서비스의 API 문서에서는 동일한 400 코드에 여러 message들을 담을 수 있어야 했기 때문에 이렇게 정리한 것인데요.

Swagger에서는 맨처음 선언한

@ApiResponse(code = 400, message = "등록되지 않은 개인 미션", response = ErrorResponse.class)

이 부분 밖에 보이지 않습니다.

위의 사진처럼 말이죠.

동일 에러에 대한 글

Swagger가 나온지 꽤나 되었음에도, 이러한 에러가 고쳐지지 않았을까 하여 찾아보니 이러한 증상을 겪으신 분이 많더라고요

https://github.com/kongchen/swagger-maven-plugin/issues/199

간략해서 말씀드리면, Swagger Core 스펙은 @ApiResponses로 이미 여러 코드 값을 작성하게 해줬으니, 동일 코드 값을 반환하는 것은 같은 @ApiResponse안에서 해결 해야 한다는 것입니다.

해결 방법

글로만 얘기하면 와닿지 않을 것 같아 코드를 바로 첨부합니다.

@ApiOperation(value = "게시글 저장")
    @ApiResponses(value = {
            @ApiResponse(code = 201, message = "저장 성공", response = PostSaveResponseDto.class),
            @ApiResponse(code = 400, message = "1.등록되지 않은 개인 미션 \t\n 2.등록되지 않은 유저 \t\n 3.하루 인증 횟수 초과", response = ErrorResponse.class)
    })

\t\n 으로 줄 바꿈하여 여러 message들을 담을 수 있기 때문에, 위와 같이 선언을 하였고, 이를 확인할 수 있었습니다.

결론

저는 ErrorHandling을 Global로 적용하였기 때문에, 모든 error가 ErrorResponse를 의존하고 있습니다. 그렇기 때문에 error에 대한 response 값을 동일하게 적용 할 수 있었습니다.

errorResponse는 따로, errorCode는 같이 하고 싶으신 분들에게는 이글이 도움이 되지 않으실 수 있습니다.

Global error설정에 관한 부분은 따로 포스팅 하겠습니다.

감사합니다.