OpenAPI 3.0 static DTO 반환 오류

개발을 하다가.. API 문서에서 오류가 발생했다.

현재 application/json으로 요청/응답하는 구조를 가지고 있는데, 이 모델이 제대로 드러나지 않는다는 것.

그리고 심지어는 뒤죽박죽 중복된 요청/응답 구조를 가지고 있었으며, 몇 개는 제대로 적어져 있었다.

나 같은 경우 위와 같은 응답 모델이 계속 중복되어 나타났다...

한 시간 정도 GPT한테도 물어보고 구글링도 해보고 해봤는데, 결국 내가 찾은 원인은 이러하다.

 

"static class에서 이름의 중복"

나는 static class를 통해 DTO를 정의한다. 그리고 동일한 구조를 갖고자 그 이름을 동일하게 가져가면서 구조를 일관적으로 하고자 한다. 예를 들어 FooDTO를 다음과 같이 작성한다.

public class FooDTO {
  public static class Main { ... }
  public static class PageItem { ... }
  public static class FooRequest { ... }
}

그리고 이와 같이 BarDTO도 존재할 수 있다.

public class BarDTO {
  public static class Main { ... }
  public static class PageItem { ... }
  public static class BarRequest { ... }
}

그런데 이 swagger는 FooDTO.Main과 BarDTO.Main을 동일한 이름을 가진 클래스 Main으로 인식한다. 이것이 문제가 되었다. 그래서 중복적인 응답이 나타난 것이다. 그러면서도 다른 이름을 가졌을 때는(Foo.FooRequest처럼) 정상 처리되는 것이다. 이를 해결하는 방법은 다음과 같다.

 

"@Schema를 통해 name 지정"

public class FooDTO {
  @Schema(name = "FooMain")
  public static class Main { ... }
  @Schema(name = "FooPageItem")
  public static class PageItem { ... }
  public static class FooRequest { ... }
}

위와 같이 @Schema 애노테이션을 통해 이름을 재정의하면, 둘은 다른 클래스로 분류되어 정상 처리된다.