[리팩토링] Swagger Request DTO 메서드 충돌 트러블슈팅

문제 상황

💡 문제 상황

 

Spring Boot + springdoc-openapi 환경에서 API 문서를 Swagger UI로 확인하던 중, 서로 다른 Request DTO임에도 Swagger에서 하나의 Schema로 인식되는 문제가 발생했다.

 

- ProductRequests.Create

public class ProductRequests {

	public record Create(
			@NotBlank(message = "상품명은 필수 입력 항목입니다.") @Size(max = 150, message = "상품명은 150자 이하여야 합니다.")
					String name,
			@NotNull(message = "업체 ID는 필수 입력 항목입니다.") UUID companyId,
			@NotNull(message = "허브 ID는 필수 입력 항목입니다.") UUID hubId) {}
}

 

- StockRequests.Create

public class StockRequests {

	public record Create(
			@NotNull(message = "수량은 필수 입력 항목입니다.") @Min(value = 0, message = "수량은 0 이상이어야 합니다.")
					int quantity,
			@NotNull(message = "상품 ID는 필수 입력 항목입니다.") UUID productId,
			@NotNull(message = "업체 ID는 필수 입력 항목입니다.") UUID companyId,
			@NotNull(message = "허브 ID는 필수 입력 항목입니다.") UUID hubId) {}
}

 

두 도메인 모두 Create라는 이름의 record를 사용하고 있었고, Controller에서는 다음과 같이 사용 중이었다.

 

- ProductController

@PostMapping("/products")
public void createProduct(@RequestBody ProductRequests.Create request) {}

 

- StockController

@PostMapping("/stocks")
public void createStock(@RequestBody StockRequests.Create request) {}

 

💡 문제 증상

• Product / Stock API가 같은 Request 구조로 표시

---

원인 분석

💡Swagger(OpenAPI)의 schema 생성 방식 문제

 

springdoc-openapi는 기본적으로 클래스의 단순 이름(Simple Name) 을 기준으로 Schema 이름을 생성한다.

schemaName = Create

 

• ProductRequests.Create
• StockRequests.Create

 

➡️ 둘 다 Swagger 입장에서는 같은 Create

 

이로 인해 Schema 이름 충돌이 발생했다. (참고)

---

해결 방안 검토

1. DTO 이름 변경

StockRequests.CreateStock

 

하지만 이 경우 Controller에서 다음과 같은 중복 표현이 발생한다.

StockRequests.CreateStock  // Stock이 두 번 반복됨

 

➡️ 도메인 구조 가독성이 나빠짐

 

2. 코드 구조는 유지하고, Swagger 문서에서만 Schema 이름을 분리

 

이를 위해 OpenAPI 전용 어노테이션인 @Schema를 사용

---

해결 방법

💡@Schema 사용

 

- 적용 코드

import io.swagger.v3.oas.annotations.media.Schema;

public class StockRequests {

    @Schema(name = "StockCreateRequest", description = "재고 생성 요청")
    public record Create(
        int quantity,
        UUID productId,
        UUID companyId,
        UUID hubId
    ) {}
}

 

Product 쪽도 동일하게 적용

@Schema(name = "ProductCreateRequest", description = "상품 생성 요청")
public record Create(
    String name,
    UUID companyId,
    UUID hubId
) {}

---

@Schema 어노테이션

@Schema는 Swagger/OpenAPI 문서 생성 시 데이터 모델(스키마)의 메타 정보(이름, 설명, 예시 등)를 정의하기 위한 어노테이션으로, 서버 로직이나 validation에는 영향을 주지 않고 API 문서를 더 명확하게 만들어 준다. (출처)

---

생각해볼 것

• 규모가 더 커져서 다양한 Request 들이 필요해질 때, @Schema 사용만으로는 유지보수가 어려워질 것 같다.
• 하나의 클래스에 관리하고 있는 Request 를 따로 분리하는 방법도 고려해봐야할 것 같다.

---

참고 자료

1) springdoc-openapi github

https://github.com/springdoc/springdoc-openapi/issues/548

Fully qualified names · Issue #548 · springdoc/springdoc-openapi