feat(core): add API versioning support for functional router endpoints

Capture version info from RequestPredicates.version() in the router
function visitor and flow it through RouterFunctionData to resolve
the appropriate SpringDocVersionStrategy (path, media-type, header,
query-param) for functional DSL routes.

Fixes #2975

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: bnasslahsen

springdoc-openapi-starter-common/src/main/java/org/springdoc/api/AbstractOpenApiResource.java

@@ -861,7 +861,9 @@ protected void getRouterFunctionPaths(String beanName, AbstractRouterFunctionVis
 		boolean withRouterOperation = routerFunctionVisitor.getRouterFunctionDatas().stream()
 				.anyMatch(routerFunctionData -> routerFunctionData.getAttributes().containsKey(OPERATION_ATTRIBUTE));
 		if (withRouterOperation) {
-			List<RouterOperation> operationList = routerFunctionVisitor.getRouterFunctionDatas().stream().map(RouterOperation::new).collect(Collectors.toList());
+			List<RouterFunctionData> datas = routerFunctionVisitor.getRouterFunctionDatas();
+			List<RouterOperation> operationList = datas.stream().map(RouterOperation::new).collect(Collectors.toList());
+			resolveRouterFunctionVersionStrategies(datas, operationList);
 			calculatePath(operationList, locale, openAPI);
 		}
 		else {
@@ -875,16 +877,48 @@ protected void getRouterFunctionPaths(String beanName, AbstractRouterFunctionVis
 			}
 			else
 				routerOperationList.addAll(Arrays.asList(routerOperations.value()));
-			if (routerOperationList.size() == 1)
-				calculatePath(routerOperationList.stream().map(routerOperation -> new RouterOperation(routerOperation, routerFunctionVisitor.getRouterFunctionDatas().get(0))).collect(Collectors.toList()), locale, openAPI);
+			if (routerOperationList.size() == 1) {
+				List<RouterFunctionData> datas = routerFunctionVisitor.getRouterFunctionDatas();
+				List<RouterOperation> operationList = routerOperationList.stream().map(routerOperation -> new RouterOperation(routerOperation, datas.get(0))).collect(Collectors.toList());
+				resolveRouterFunctionVersionStrategies(datas, operationList);
+				calculatePath(operationList, locale, openAPI);
+			}
 			else {
+				List<RouterFunctionData> datas = routerFunctionVisitor.getRouterFunctionDatas();
 				List<RouterOperation> operationList = routerOperationList.stream().map(RouterOperation::new).collect(Collectors.toList());
-				mergeRouters(routerFunctionVisitor.getRouterFunctionDatas(), operationList);
+				mergeRouters(datas, operationList);
+				resolveRouterFunctionVersionStrategies(datas, operationList);
 				calculatePath(operationList, locale, openAPI);
 			}
 		}
 	}
 
+	/**
+	 * Resolve version strategies for router function operations.
+	 *
+	 * @param datas      the router function datas
+	 * @param operations the router operations
+	 */
+	private void resolveRouterFunctionVersionStrategies(List<RouterFunctionData> datas, List<RouterOperation> operations) {
+		springDocProviders.getSpringWebProvider().ifPresent(springWebProvider -> {
+			for (int i = 0; i < operations.size() && i < datas.size(); i++) {
+				String version = datas.get(i).getVersion();
+				if (version != null) {
+					RouterOperation op = operations.get(i);
+					SpringDocVersionStrategy strategy = springWebProvider.getSpringDocVersionStrategy(version, datas.get(i).getParams());
+					if (strategy != null) {
+						// Ensure version is set for functional routes where params may be empty
+						if (strategy.getVersion() == null) {
+							strategy.setVersion(version);
+						}
+						op.setPath(strategy.updateOperationPath(op.getPath(), version));
+					}
+					op.setVersionStrategy(strategy);
+				}
+			}
+		});
+	}
+
 	/**
 	 * Is filter condition boolean.
 	 *

springdoc-openapi-starter-common/src/main/java/org/springdoc/core/fn/AbstractRouterFunctionVisitor.java

@@ -91,6 +91,11 @@ public class AbstractRouterFunctionVisitor {
 	 */
 	protected Map<String, Object> attributes = new LinkedHashMap<>();
 
+	/**
+	 * The Version.
+	 */
+	private String version;
+
 	/**
 	 * The Level.
 	 */
@@ -178,6 +183,15 @@ public void queryParam(String name, String value) {
 			currentRouterFunctionDatas.forEach(routerFunctionData -> routerFunctionData.addQueryParams(name, value));
 	}
 
+	/**
+	 * Version.
+	 *
+	 * @param version the version
+	 */
+	public void version(String version) {
+		this.version = version;
+	}
+
 	/**
 	 * Path extension.
 	 *
@@ -282,8 +296,15 @@ protected void commonStartNested() {
 	 * Common route.
 	 */
 	protected void commonRoute() {
+		String currentVersion = this.version;
+		this.version = null;
 		this.routerFunctionDatas.addAll(currentRouterFunctionDatas);
-		currentRouterFunctionDatas.forEach(routerFunctionData -> routerFunctionData.addAttributes(this.attributes));
+		currentRouterFunctionDatas.forEach(routerFunctionData -> {
+			routerFunctionData.addAttributes(this.attributes);
+			if (currentVersion != null) {
+				routerFunctionData.setVersion(currentVersion);
+			}
+		});
 		this.attributes = new HashMap<>();
 	}
 

springdoc-openapi-starter-common/src/main/java/org/springdoc/core/fn/RouterFunctionData.java

@@ -83,6 +83,11 @@ public class RouterFunctionData {
 	 */
 	private RequestMethod[] methods;
 
+	/**
+	 * The Version.
+	 */
+	private String version;
+
 	/**
 	 * The Attributes.
 	 */
@@ -109,6 +114,7 @@ public RouterFunctionData(String nestedOrPath, RouterFunctionData functionData)
 		this.queryParams = functionData.getQueryParams();
 		this.methods = functionData.getMethods();
 		this.attributes = functionData.getAttributes();
+		this.version = functionData.getVersion();
 	}
 
 	/**
@@ -312,4 +318,22 @@ public Map<String, Object> getAttributes() {
 	public void addAttributes(Map<String, Object> attributes) {
 		this.attributes.putAll(attributes);
 	}
+
+	/**
+	 * Gets version.
+	 *
+	 * @return the version
+	 */
+	public String getVersion() {
+		return version;
+	}
+
+	/**
+	 * Sets version.
+	 *
+	 * @param version the version
+	 */
+	public void setVersion(String version) {
+		this.version = version;
+	}
 }

springdoc-openapi-starter-webflux-api/src/main/java/org/springdoc/webflux/core/visitor/RouterFunctionVisitor.java

@@ -92,11 +92,6 @@ public void unknown(RouterFunction<?> routerFunction) {
 		// Not yet needed
 	}
 
-	@Override
-	public void version(String version) {
-		// Not yet needed
-	}
-
 	@Override
 	public void unknown(RequestPredicate predicate) {
 		// Not yet needed

springdoc-openapi-starter-webmvc-api/src/main/java/org/springdoc/webmvc/core/providers/RouterFunctionWebMvcProvider.java

@@ -107,11 +107,6 @@ public void unknown(RouterFunction<?> routerFunction) {
 			// Not yet needed
 		}
 
-		@Override
-		public void version(String version) {
-			// Not yet needed
-		}
-
 		@Override
 		public void unknown(RequestPredicate predicate) {
 			// Not yet needed

springdoc-openapi-starter-webmvc-api/src/test/java/test/org/springdoc/api/v31/app255/SpringDocApp255Test.java

@@ -0,0 +1,43 @@
+/*
+ *
+ *  *
+ *  *  *
+ *  *  *  *
+ *  *  *  *  * Copyright 2019-2025 the original author or authors.
+ *  *  *  *  *
+ *  *  *  *  * Licensed under the Apache License, Version 2.0 (the "License");
+ *  *  *  *  * you may not use this file except in compliance with the License.
+ *  *  *  *  * You may obtain a copy of the License at
+ *  *  *  *  *
+ *  *  *  *  *      https://www.apache.org/licenses/LICENSE-2.0
+ *  *  *  *  *
+ *  *  *  *  * Unless required by applicable law or agreed to in writing, software
+ *  *  *  *  * distributed under the License is distributed on an "AS IS" BASIS,
+ *  *  *  *  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  *  *  *  * See the License for the specific language governing permissions and
+ *  *  *  *  * limitations under the License.
+ *  *  *  *
+ *  *  *
+ *  *
+ *
+ */
+
+package test.org.springdoc.api.v31.app255;
+
+import test.org.springdoc.api.v31.AbstractSpringDocTest;
+
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+/**
+ * Tests API versioning support for functional router endpoints.
+ *
+ * @author bnasslahsen
+ */
+public class SpringDocApp255Test extends AbstractSpringDocTest {
+
+	@SpringBootApplication
+	static class SpringDocTestApp {
+
+	}
+
+}

springdoc-openapi-starter-webmvc-api/src/test/java/test/org/springdoc/api/v31/app255/UserHandler.java

@@ -0,0 +1,50 @@
+/*
+ *
+ *  *
+ *  *  *
+ *  *  *  *
+ *  *  *  *  * Copyright 2019-2025 the original author or authors.
+ *  *  *  *  *
+ *  *  *  *  * Licensed under the Apache License, Version 2.0 (the "License");
+ *  *  *  *  * you may not use this file except in compliance with the License.
+ *  *  *  *  * You may obtain a copy of the License at
+ *  *  *  *  *
+ *  *  *  *  *      https://www.apache.org/licenses/LICENSE-2.0
+ *  *  *  *  *
+ *  *  *  *  * Unless required by applicable law or agreed to in writing, software
+ *  *  *  *  * distributed under the License is distributed on an "AS IS" BASIS,
+ *  *  *  *  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  *  *  *  * See the License for the specific language governing permissions and
+ *  *  *  *  * limitations under the License.
+ *  *  *  *
+ *  *  *
+ *  *
+ *
+ */
+
+package test.org.springdoc.api.v31.app255;
+
+import java.util.List;
+
+import org.springframework.stereotype.Component;
+import org.springframework.web.servlet.function.ServerRequest;
+import org.springframework.web.servlet.function.ServerResponse;
+
+/**
+ * The type User handler.
+ *
+ * @author bnasslahsen
+ */
+@Component
+public class UserHandler {
+
+	/**
+	 * Find all server response.
+	 * @param request the request
+	 * @return the server response
+	 */
+	public ServerResponse findAll(ServerRequest request) {
+		return ServerResponse.ok().body(List.of("user1", "user2"));
+	}
+
+}

springdoc-openapi-starter-webmvc-api/src/test/java/test/org/springdoc/api/v31/app255/UserRouterConfig.java

@@ -0,0 +1,58 @@
+/*
+ *
+ *  *
+ *  *  *
+ *  *  *  *
+ *  *  *  *  * Copyright 2019-2025 the original author or authors.
+ *  *  *  *  *
+ *  *  *  *  * Licensed under the Apache License, Version 2.0 (the "License");
+ *  *  *  *  * you may not use this file except in compliance with the License.
+ *  *  *  *  * You may obtain a copy of the License at
+ *  *  *  *  *
+ *  *  *  *  *      https://www.apache.org/licenses/LICENSE-2.0
+ *  *  *  *  *
+ *  *  *  *  * Unless required by applicable law or agreed to in writing, software
+ *  *  *  *  * distributed under the License is distributed on an "AS IS" BASIS,
+ *  *  *  *  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  *  *  *  * See the License for the specific language governing permissions and
+ *  *  *  *  * limitations under the License.
+ *  *  *  *
+ *  *  *
+ *  *
+ *
+ */
+
+package test.org.springdoc.api.v31.app255;
+
+import org.springdoc.webmvc.core.fn.SpringdocRouteBuilder;
+
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.web.servlet.function.RequestPredicates;
+import org.springframework.web.servlet.function.RouterFunction;
+import org.springframework.web.servlet.function.ServerResponse;
+
+/**
+ * The type User router config.
+ *
+ * @author bnasslahsen
+ */
+@Configuration
+public class UserRouterConfig {
+
+	/**
+	 * Routes router function.
+	 *
+	 * @param handler the handler
+	 * @return the router function
+	 */
+	@Bean
+	RouterFunction<ServerResponse> routes(UserHandler handler) {
+		return SpringdocRouteBuilder.route()
+				.GET("/api/{version}/users", RequestPredicates.version("1.0"),
+						handler::findAll,
+						ops -> ops.beanClass(UserHandler.class).beanMethod("findAll"))
+				.build();
+	}
+
+}

springdoc-openapi-starter-webmvc-api/src/test/java/test/org/springdoc/api/v31/app255/config/ApiVersionParser.java

@@ -0,0 +1,24 @@
+package test.org.springdoc.api.v31.app255.config;
+
+public class ApiVersionParser implements org.springframework.web.accept.ApiVersionParser {
+
+    // allows us to use /api/v2/users instead of /api/2.0/users
+    @Override
+    public Comparable parseVersion(String version) {
+        // Remove "v" prefix if it exists (v1 becomes 1, v2 becomes 2)
+        if (version.startsWith("v") || version.startsWith("V")) {
+            version = version.substring(1);
+        }
+		
+		if("api-docs".equals(version) || "index.html".equals(version) 
+				|| "swagger-ui-bundle.js".equals(version)
+				|| "swagger-ui.css".equals(version)
+				|| "index.css".equals(version)
+				|| "swagger-ui-standalone-preset.js".equals(version)
+				|| "favicon-32x32.png".equals(version)
+				|| "favicon-16x16.png".equals(version)
+				|| "swagger-initializer.js".equals(version)) 
+			return null;
+        return version;
+    }
+}

springdoc-openapi-starter-webmvc-api/src/test/java/test/org/springdoc/api/v31/app255/config/WebConfig.java

@@ -0,0 +1,21 @@
+package test.org.springdoc.api.v31.app255.config;
+
+import org.springframework.context.annotation.Configuration;
+import org.springframework.web.servlet.config.annotation.ApiVersionConfigurer;
+import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
+
+@Configuration
+public class WebConfig implements WebMvcConfigurer {
+
+    @Override
+    public void configureApiVersioning(ApiVersionConfigurer configurer) {
+        configurer
+                .usePathSegment(1)
+				.detectSupportedVersions(false)
+                .addSupportedVersions("1.0","2.0")
+                .setDefaultVersion("1.0")
+				.setVersionRequired(false)
+                .setVersionParser(new ApiVersionParser());
+    }
+
+}