API Version

API 버전 관리를 활성화하려면, WebMvcConfigurer의 ApiVersionConfigurer 콜백을 사용하십시오:

1@Configuration
2public class WebConfiguration implements WebMvcConfigurer {
3
4	@Override
5	public void configureApiVersioning(ApiVersionConfigurer configurer) {
6		configurer.useRequestHeader("API-Version");
7	}
8}

1@Configuration
2class WebConfiguration : WebMvcConfigurer {
3
4	override fun configureApiVersioning(configurer: ApiVersionConfigurer) {
5		configurer.useRequestHeader("API-Version")
6	}
7}

아래에 나열된 기본 제공 옵션 중 하나를 통해 버전을 해석하거나, 대안으로 커스텀 ApiVersionResolver를 사용할 수 있습니다:

요청 헤더
요청 파라미터
경로 세그먼트
미디어 타입 파라미터

경로 세그먼트에서 해석하려면, 버전을 포함할 것으로 예상되는 경로 세그먼트의 인덱스를 지정해야 합니다. 경로 세그먼트는 URI 변수로 선언되어야 합니다. 예: "/{version}", "/api/{version}" 등과 같이, 실제 이름은 중요하지 않습니다.

버전은 일반적으로 경로의 시작 부분에 있으므로, 모든 핸들러에 대한 공통 경로 프리픽스로 외부에서 구성하는 것을 고려하고, Path Matching 옵션을 통해 설정하십시오.

기본적으로, 버전은 SemanticVersionParser로 파싱되지만, 커스텀 ApiVersionParser를 구성할 수도 있습니다.

지원되는 버전은 편의를 위해 요청 매핑에 선언된 버전으로부터 투명하게 감지되지만, MVC 설정의 플래그를 통해 이를 끌 수 있고, 설정에서 명시적으로 구성된 버전만을 지원되는 것으로 간주할 수 있습니다.

지원되지 않는 버전을 가진 요청은 InvalidApiVersionException으로 거부되며 400 응답이 발생합니다.

클라이언트에게 더 이상 사용되지 않는(deprecated) 버전에 대한 정보를 보내기 위해 ApiVersionDeprecationHandler를 설정할 수 있습니다. 기본 제공 표준 핸들러는 RFC 9745 및 RFC 8594를 기반으로 "Deprecation", "Sunset", "Link" 헤더를 설정할 수 있습니다.

API 버전 관리가 구성되면, 요청 버전에 따라 컨트롤러 메서드에 요청을 매핑하기 시작할 수 있습니다.