Ignore: 🔧 Swagger 에러 정의 어노테이션

[psychology50]

작업 이유

기존 에러 응답을 정의하기 위해, 예상 응답을 직접 문자열로 작성해야만 하는 문제가 있음.
예외 정보가 수정될 때마다 개발자가 해당 예외가 문서에 명시되어 있는 부분을 모두 찾아서 수정해야 한다는 번거로움과 휴먼 에러로 인한 문제점 존재.

작업 사항

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiExceptionExplanation {
    Class<? extends BaseErrorCode> value();

    /**
     * BaseErrorCode를 구현한 Enum 클래스의 상수명
     */
    String constant();

    String name() default "";

    String mediaType() default "application/json";

    String summary() default "";

    String description() default "";
}

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiResponseExplanations {
    ApiExceptionExplanation[] errors() default {};
}

• 2가지 어노테이션을 활용하여 문제를 개선.
  • @ApiExceptionExplanation: 에러 상세 스펙을 정의함.
  • @ApiResponseExplanations: 복수개의 에러 스펙을 하나로 묶기 위한 어노테이션

위와 같이 정의하면 똑같이 문서에 정의되도록 개선함.

리뷰어가 중점적으로 확인해야 하는 부분

한 가지 단점은 @interface의 특성 상, 필드로 Enum 혹은 인터페이스 타입을 갖지 못함. (자바의 어노테이션은 컴파일 시점에 타입이 결정되어야 하기 때문)
따라서, 특정 상수값을 넘겨주기 위해선 어쩔 수 없이 BaseErrorCode를 구현한 enum 클래스 정보와 사용하려는 필드명을 문자열로 넘겨주어야만 함.

문자열에 완전히 종속되는 문제를 회피하지 못 한 건 매우 아쉽지만, 적어도 위 방식을 사용하면 강제로 컴파일 타입에 실패하게 만들 수는 있으므로 문서에 예외 정보가 잘못 기입되는 경우는 회피할 수 있음.

발견한 이슈

• 없음