Add API versioning reference documentation

See gh-34569

framework-docs/modules/ROOT/pages/web/webmvc/mvc-config/api-version.adoc

@@ -0,0 +1,26 @@
+[[mvc-config-api-version]]
+= API Version
+
+[.small]#xref:web/webflux/config.adoc#webflux-config-api-version[See equivalent in the Reactive stack]#
+
+To enable API versioning with a request header, use the following:
+
+include-code::./WebConfiguration[tag=snippet,indent=0]
+
+Alternatively, the version can be resolved from a request parameter, from a path segment,
+or  through a custom `ApiVersionResolver`.
+
+TIP: When resolving from a path segment, consider configuring a path prefix once in
+xref:web/webmvc/mvc-config/path-matching.adoc[Path Matching] options.
+
+Raw version values are parsed with `SemanticVersionParser` by default, but you can use
+a custom xref:web/webmvc-versioning.adoc#mvc-versioning-parser[ApiVersionParser].
+
+"Supported" versions are transparently detected from versions declared in request mappings
+for convenience, but you can also set the list of supported versions explicitly, and
+ignore declared ones. Requests with a version that is not supported are rejected with an
+`InvalidApiVersionException` resulting in a 400 response.
+
+Once API versioning is configured, you can begin to map requests to
+xref:web/webmvc/mvc-controller/ann-requestmapping.adoc#mvc-ann-requestmapping-version[controller methods]
+according to the request version.

framework-docs/modules/ROOT/pages/web/webmvc/mvc-controller/ann-requestmapping.adoc

@@ -429,6 +429,86 @@ xref:web/webmvc/mvc-controller/ann-requestmapping.adoc#mvc-ann-requestmapping-co
 instead.
 
 
+[[mvc-ann-requestmapping-version]]
+== API Version
+[.small]#xref:web/webflux/controller/ann-requestmapping.adoc#webflux-ann-requestmapping-version[See equivalent in the Reactive stack]#
+
+There is no standard way to specify an API version, so you need to configure that first
+through the xref:web/webmvc/mvc-config/api-version.adoc[MVC Config] along with other
+config options. This results in the creation of an
+xref:web/webmvc-versioning.adoc#mvc-versioning-strategy[ApiVersionStrategy] that in turn
+supports request mapping.
+
+Once API versioning is enabled, you can begin to map requests with versions.
+The `@RequestMapping` version attribute supports the following:
+
+- No value -- match any version
+- Fixed version ("1.2") -- match the given version only
+- Baseline version ("1.2+") -- match the given version and above
+
+If multiple controller methods have a version less than or equal to the request version,
+the one closest to the request version is considered for mapping purposes,
+in effect superseding the rest.
+
+To illustrate this, consider the following controller mappings:
+
+[tabs]
+======
+Java::
++
+[source,java,indent=0,subs="verbatim,quotes"]
+----
+	@RestController
+	@RequestMapping("/account/{id}")
+	public class AccountController {
+
+		@GetMapping // <1>
+		public Account getAccount() {
+		}
+
+		@GetMapping(version = "1.1") // <2>
+		public Account getAccount1_1() {
+		}
+
+		@GetMapping(version = "1.2+") // <3>
+		public Account getAccount1_2() {
+		}
+
+		@GetMapping(version = "1.5") // <4>
+		public Account getAccount1_5() {
+		}
+	}
+----
+<1> match any version
+<2> match version 1.1
+<3> match version 1.2 and above
+<4> match version 1.5
+======
+
+For request with version `"1.3"`:
+
+- (1) matches as it matches any version
+- (2) does not match
+- (3) matches as it matches 1.2 and above, and is *chosen* as the highest match
+- (4) is higher and does not match
+
+For request with version `"1.5"`:
+
+- (1) matches as it matches any version
+- (2) does not match
+- (3) matches as it matches 1.2 and above
+- (4) matches and is *chosen* as the highest match
+
+A request with version `"1.6"` does not have a match. (1) and (3) do match, but are
+superseded by (4), which does not match. In this scenario, `NotAcceptableApiVersionException`
+is raised resulting in a 400 response.
+
+NOTE: The above assumes the request version is a "supported" versions. If not it would
+fail xref:web/webmvc-versioning.adoc#mvc-versioning-validation[Validation].
+
+
+
+
 [[mvc-ann-requestmapping-head-options]]
 == HTTP HEAD, OPTIONS
 [.small]#xref:web/webflux/controller/ann-requestmapping.adoc#webflux-ann-requestmapping-head-options[See equivalent in the Reactive stack]#