Swagger 1.2에서 2.0으로 마이그레이션: @ApiModel과 @ApiModelProperty의 필요성

Swagger 1.2에서 2.0으로 마이그레이션할 때, 많은 개발자들이 @ApiModel과 @ApiModelProperty 어노테이션의 역할과 필요성에 대해 혼란스러워합니다. 이 글에서는 이 두 어노테이션이 Swagger 2.0에서 어떻게 변화했는지, 그리고 현대적인 API 문서화 표준인 **OpenAPI 3.0**과의 관계를 중심으로 마이그레이션 방법을 자세히 알아보겠습니다.

1. Swagger 2.0 및 OpenAPI 3.0에서의 어노테이션 변경

Swagger 2.0(OpenAPI 2.0)으로 넘어오면서 기존의 @ApiModel과 @ApiModelProperty 어노테이션은 여전히 사용할 수 있습니다. 그러나 OpenAPI 3.0 스펙이 발표된 이후, 스프링폭스(Springfox)와 같은 라이브러리들은 새로운 표준에 맞춰 어노테이션을 제공하기 시작했습니다. 그 핵심은 바로 @Schema 어노테이션입니다. @Schema는 기존의 두 어노테이션의 역할을 모두 통합하여 더욱 유연하고 강력한 문서화 기능을 제공합니다.

기존 Swagger 1.2의 @ApiModel과 @ApiModelProperty는 OpenAPI 3.0의 @Schema로 대체되었습니다.
따라서, 새로운 프로젝트에서는 @Schema를 사용하는 것이 권장됩니다.

2. 마이그레이션 단계

Swagger 1.2 기반의 프로젝트를 2.0(또는 OpenAPI 3.0)으로 전환하는 단계는 다음과 같습니다.

2.1. 의존성 업데이트

먼저, 프로젝트의 빌드 파일(pom.xml 또는 build.gradle)에서 Swagger 라이브러리를 최신 버전으로 업데이트해야 합니다. 예를 들어, Maven과 Springfox를 사용한다면:



    io.springfox
    springfox-boot-starter
    3.0.0

이후 OpenAPI 3.0을 지원하는 springdoc-openapi와 같은 라이브러리로 전환하는 것도 좋은 선택입니다.

2.2. 어노테이션 변경

기존에 사용하던 어노테이션을 새로운 @Schema로 변경해야 합니다. 아래는 간단한 변경 예시입니다.


// 기존 Swagger 1.2 어노테이션
@ApiModel(value = "MyResponse", description = "응답 모델")
class MyResponse {
    @ApiModelProperty(value = "응답 메시지", required = true)
    private String message;
    
    // ...
}

// Swagger 2.0 (OpenAPI 3.0) 어노테이션
@Schema(description = "응답 모델")
class MyResponse {
    @Schema(description = "응답 메시지", required = true)
    private String message;

    // ...
}

3. @Schema 사용의 이점

@Schema 어노테이션을 사용하면 다음과 같은 이점을 얻을 수 있습니다.

더 풍부한 메타데이터: @Schema는 기존 어노테이션보다 더 다양한 속성(example, defaultValue, minLength, maxLength 등)을 제공하여 API 모델을 훨씬 상세하게 설명할 수 있습니다.
OpenAPI 3.0 호환성: @Schema는 OpenAPI 3.0 스펙과 완벽하게 호환되므로, 미래 지향적인 API 문서화를 지원합니다.
코드 일관성: 모델과 관련된 모든 문서화 정보를 @Schema로 통일하여 코드의 가독성과 일관성을 높일 수 있습니다.

4. 모범 사례

명시적 문서화: 비록 일부 정보(예: 필드명)는 자동으로 문서화되지만, @Schema를 사용하여 필드의 목적, 제약 조건 등을 명시적으로 문서화하는 것이 좋습니다.
점진적 마이그레이션: 대규모 프로젝트의 경우, 모든 파일을 한 번에 바꾸기보다는 점진적으로 어노테이션을 업데이트하는 전략을 사용하세요.
테스트 강화: 마이그레이션 후 반드시 Swagger UI나 기타 문서화 도구를 통해 API 문서가 의도한 대로 정확하게 생성되었는지 확인하세요.

결론

Swagger 1.2에서 2.0으로 마이그레이션할 때, **@ApiModel과 @ApiModelProperty 어노테이션은 필수는 아니지만**, 새로운 표준인 **@Schema로 대체하여 사용하는 것이 강력히 권장됩니다.** 이를 통해 더 풍부하고 정확한 API 문서를 생성하고, OpenAPI 3.0과의 호환성도 확보할 수 있습니다. 마이그레이션 과정에서 이러한 변경사항을 점진적으로 적용하면, API 문서화의 품질을 크게 향상시킬 수 있습니다.