Add support for Spring Framework API Versioning with Functional Endpoints. Fixes #3229

Author: bnasslahsen

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

@@ -105,6 +105,7 @@
 import org.springdoc.core.providers.JavadocProvider;
 import org.springdoc.core.providers.ObjectMapperProvider;
 import org.springdoc.core.providers.SpringDocProviders;
+import org.springdoc.core.providers.SpringWebProvider;
 import org.springdoc.core.service.AbstractRequestService;
 import org.springdoc.core.service.GenericParameterService;
 import org.springdoc.core.service.GenericResponseService;
@@ -585,6 +586,13 @@ protected void calculatePath(HandlerMethod handlerMethod, RouterOperation router
 		String[] headers = routerOperation.getHeaders();
 		Map<String, String> queryParams = routerOperation.getQueryParams();
 		SpringDocVersionStrategy springDocVersionStrategy = routerOperation.getSpringDocVersionStrategy();
+		if (springDocVersionStrategy == null && routerOperation.getVersion() != null) {
+			Optional<SpringWebProvider> springWebProviderOpt = springDocProviders.getSpringWebProvider();
+			if (springWebProviderOpt.isPresent()) {
+				springDocVersionStrategy = springWebProviderOpt.get().getSpringDocVersionStrategy(
+						routerOperation.getVersion(), routerOperation.getParams());
+			}
+		}
 		if (springDocVersionStrategy != null)
 			queryParams = springDocVersionStrategy.updateQueryParams(queryParams);
 		Components components = openAPI.getComponents();
@@ -880,14 +888,12 @@ protected void getRouterFunctionPaths(String beanName, AbstractRouterFunctionVis
 			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(datas, operationList);
-				resolveRouterFunctionVersionStrategies(datas, operationList);
 				calculatePath(operationList, locale, openAPI);
 			}
 		}
@@ -907,13 +913,9 @@ private void resolveRouterFunctionVersionStrategies(List<RouterFunctionData> dat
 					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);
+					op.setVersion(version);
 				}
 			}
 		});

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

@@ -113,6 +113,11 @@ public class RouterOperation implements Comparable<RouterOperation> {
 	 */
 	private SpringDocVersionStrategy springDocVersionStrategy;
 
+	/**
+	 * The Version.
+	 */
+	private String version;
+
 	/**
 	 * Instantiates a new Router operation.
 	 */
@@ -155,6 +160,7 @@ public RouterOperation(org.springdoc.core.annotations.RouterOperation routerOper
 		this.headers = ArrayUtils.isEmpty(routerOperationAnnotation.headers()) ? routerFunctionData.getHeaders() : routerOperationAnnotation.headers();
 		this.params = routerOperationAnnotation.params();
 		this.queryParams = routerFunctionData.getQueryParams();
+		this.version = routerFunctionData.getVersion();
 	}
 
 	/**
@@ -191,6 +197,7 @@ public RouterOperation(RouterFunctionData routerFunctionData) {
 		this.headers = routerFunctionData.getHeaders();
 		this.params = routerFunctionData.getParams();
 		this.queryParams = routerFunctionData.getQueryParams();
+		this.version = routerFunctionData.getVersion();
 
 		Map<String, Object> attributes = routerFunctionData.getAttributes();
 		if (attributes.containsKey(OPERATION_ATTRIBUTE)) {
@@ -448,6 +455,24 @@ public void setVersionStrategy(SpringDocVersionStrategy springDocVersionStrategy
 		this.springDocVersionStrategy = springDocVersionStrategy;
 	}
 
+	/**
+	 * Gets version.
+	 *
+	 * @return the version
+	 */
+	public String getVersion() {
+		return version;
+	}
+
+	/**
+	 * Sets version.
+	 *
+	 * @param version the version
+	 */
+	public void setVersion(String version) {
+		this.version = version;
+	}
+
 	@Override
 	public int compareTo(RouterOperation routerOperation) {
 		int result = path.compareTo(routerOperation.getPath());

springdoc-openapi-starter-common/src/main/java/org/springdoc/core/versions/QueryParamVersionStrategy.java

@@ -28,6 +28,8 @@
 import java.util.LinkedHashMap;
 import java.util.Map;
 
+import org.apache.commons.lang3.ArrayUtils;
+
 /**
  * The type Query param version strategy.
  *
@@ -64,6 +66,10 @@ public String getParameterName() {
 
 	@Override
 	public void updateVersion(String version, String[] params) {
+		if(ArrayUtils.isEmpty(params)) { 
+			setVersion(version);
+			return;
+		}
 		for (String param : params) {
 			if (param.contains("=")) {
 				String[] paramValues = param.split("=", 2);

springdoc-openapi-starter-webflux-api/src/test/java/test/org/springdoc/api/v31/app199/SpringDocApp199Test.java

@@ -0,0 +1,45 @@
+/*
+ *
+ *  *
+ *  *  *
+ *  *  *  *
+ *  *  *  *  * 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.app199;
+
+import test.org.springdoc.api.v31.AbstractSpringDocTest;
+
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+import org.springframework.context.annotation.ComponentScan;
+
+/**
+ * Tests media-type versioning support for functional router endpoints.
+ *
+ * @author bnasslahsen
+ */
+public class SpringDocApp199Test extends AbstractSpringDocTest {
+
+	@SpringBootApplication
+	@ComponentScan(basePackages = { "org.springdoc", "test.org.springdoc.api.v31.app199" })
+	static class SpringDocTestApp {
+
+	}
+
+}

springdoc-openapi-starter-webflux-api/src/test/java/test/org/springdoc/api/v31/app199/UserHandler.java

@@ -0,0 +1,69 @@
+/*
+ *
+ *  *
+ *  *  *
+ *  *  *  *
+ *  *  *  *  * 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.app199;
+
+import reactor.core.publisher.Mono;
+
+import org.springframework.stereotype.Component;
+import org.springframework.web.reactive.function.server.ServerRequest;
+import org.springframework.web.reactive.function.server.ServerResponse;
+
+/**
+ * The type User handler.
+ *
+ * @author bnasslahsen
+ */
+@Component
+public class UserHandler {
+
+	private final UserService userService;
+
+	/**
+	 * Instantiates a new User handler.
+	 * @param userService the user service
+	 */
+	public UserHandler(UserService userService) {
+		this.userService = userService;
+	}
+
+	/**
+	 * Get users media v1.
+	 * @param request the request
+	 * @return the server response
+	 */
+	public Mono<ServerResponse> getUsersMediaV1(ServerRequest request) {
+		return ServerResponse.ok().bodyValue(userService.getUsersMediaV1());
+	}
+
+	/**
+	 * Get users media v2.
+	 * @param request the request
+	 * @return the server response
+	 */
+	public Mono<ServerResponse> getUsersMediaV2(ServerRequest request) {
+		return ServerResponse.ok().bodyValue(userService.getUsersMediaV2());
+	}
+
+}

springdoc-openapi-starter-webflux-api/src/test/java/test/org/springdoc/api/v31/app199/UserRouterConfig.java

@@ -0,0 +1,61 @@
+/*
+ *
+ *  *
+ *  *  *
+ *  *  *  *
+ *  *  *  *  * 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.app199;
+
+import org.springdoc.webflux.core.fn.SpringdocRouteBuilder;
+
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.http.MediaType;
+import org.springframework.web.reactive.function.server.RequestPredicates;
+import org.springframework.web.reactive.function.server.RouterFunction;
+import org.springframework.web.reactive.function.server.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/users/media",
+					RequestPredicates.version("1.0").and(RequestPredicates.accept(MediaType.APPLICATION_JSON)),
+					handler::getUsersMediaV1, ops -> ops.beanClass(UserService.class).beanMethod("getUsersMediaV1"))
+			.GET("/api/users/media",
+					RequestPredicates.version("2.0").and(RequestPredicates.accept(MediaType.APPLICATION_JSON)),
+					handler::getUsersMediaV2, ops -> ops.beanClass(UserService.class).beanMethod("getUsersMediaV2"))
+			.build();
+	}
+
+}

springdoc-openapi-starter-webflux-api/src/test/java/test/org/springdoc/api/v31/app199/UserService.java

@@ -0,0 +1,75 @@
+/*
+ *
+ *  *
+ *  *  *
+ *  *  *  *
+ *  *  *  *  * 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.app199;
+
+import java.util.List;
+import java.util.stream.Collectors;
+
+import test.org.springdoc.api.v31.app199.user.UserDTOv1;
+import test.org.springdoc.api.v31.app199.user.UserDTOv2;
+import test.org.springdoc.api.v31.app199.user.UserMapper;
+import test.org.springdoc.api.v31.app199.user.UserRepository;
+
+import org.springframework.stereotype.Service;
+
+/**
+ * The type User service. Provides typed return methods for springdoc introspection.
+ *
+ * @author bnasslahsen
+ */
+@Service
+public class UserService {
+
+	private final UserRepository userRepository;
+
+	private final UserMapper userMapper;
+
+	/**
+	 * Instantiates a new User service.
+	 * @param userRepository the user repository
+	 * @param userMapper the user mapper
+	 */
+	public UserService(UserRepository userRepository, UserMapper userMapper) {
+		this.userRepository = userRepository;
+		this.userMapper = userMapper;
+	}
+
+	/**
+	 * Gets users media v1.
+	 * @return the users v1
+	 */
+	public List<UserDTOv1> getUsersMediaV1() {
+		return userRepository.findAll().stream().map(userMapper::toV1).collect(Collectors.toList());
+	}
+
+	/**
+	 * Gets users media v2.
+	 * @return the users v2
+	 */
+	public List<UserDTOv2> getUsersMediaV2() {
+		return userRepository.findAll().stream().map(userMapper::toV2).collect(Collectors.toList());
+	}
+
+}