API バージョン

Reactive スタックに相当する部分を参照

API のバージョン管理を有効にするには、WebMvcConfigurer の ApiVersionConfigurer コールバックを使用します。

  • Java

  • Kotlin

@Configuration
public class WebConfiguration implements WebMvcConfigurer {

	@Override
	public void configureApiVersioning(ApiVersionConfigurer configurer) {
		configurer.useRequestHeader("API-Version");
	}
}
@Configuration
class WebConfiguration : WebMvcConfigurer {

	override fun configureApiVersioning(configurer: ApiVersionConfigurer) {
		configurer.useRequestHeader("API-Version")
	}
}

以下にリストされている組み込みオプションのいずれかを使用してバージョンを解決するか、カスタム ApiVersionResolver を使用することもできます。

  • リクエストヘッダー

  • リクエストパラメーター

  • パスセグメント

  • メディア型パラメーター

パスセグメントから解決するには、バージョンを含むと想定されるパスセグメントのインデックスを指定する必要があります。パスセグメントは URI 変数として宣言する必要があります（例: "/{version}",、/api/{version}", など）。実際の名前は重要ではありません。バージョンは通常パスの先頭にあるため、パスマッチングオプションを使用して、すべてのハンドラーの共通パスプレフィックスとして外部的に設定することを検討してください。

デフォルトでは、バージョンは SemanticVersionParser で解析されますが、カスタム ApiVersionParser を構成することもできます。

サポートされているバージョンは、便宜上、リクエストマッピングで宣言されたバージョンから透過的に検出されます。ただし、MVC 設定のフラグでこの機能をオフにし、設定で明示的に指定されたバージョンのみをサポート対象とすることもできます。サポートされていないバージョンのリクエストは、InvalidApiVersionException で拒否され、400 レスポンスが返されます。

ApiVersionDeprecationHandler を設定することで、非推奨バージョンに関する情報をクライアントに送信できます。組み込みの標準ハンドラーは、RFC 9745 [IETF] (英語) および RFC 8594 [IETF] (英語) に基づいて、"Deprecation"、"Sunset"、"Link" ヘッダーを設定できます。

API のバージョン管理が設定されると、リクエストのバージョンに応じてリクエストをコントローラーメソッドにマッピングできるようになります。