Spring Framework 7 - API versioning support #2975

Author: bnasslahsen

pom.xml

@@ -11,7 +11,7 @@
 	<parent>
 		<groupId>org.springframework.boot</groupId>
 		<artifactId>spring-boot-starter-parent</artifactId>
-		<version>4.0.0-RC1</version>
+		<version>4.0.0-SNAPSHOT</version>
 	</parent>
 
 	<licenses>
@@ -65,6 +65,7 @@
 		</spring-security-oauth2-authorization-server.version>
 		<scalar.version>0.3.12</scalar.version>
 		<skipPublishing>false</skipPublishing>
+		<spring-framework.version>7.0.0-SNAPSHOT</spring-framework.version>
 	</properties>
 
 	<dependencyManagement>
@@ -248,4 +249,15 @@
 			</build>
 		</profile>
 	</profiles>
+
+	<repositories>
+		<repository>
+			<id>spring-snapshots</id>
+			<name>Spring Snapshots</name>
+			<url>https://repo.spring.io/snapshot</url>
+			<snapshots>
+				<enabled>true</enabled>
+			</snapshots>
+		</repository>
+	</repositories>
 </project>

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

@@ -43,7 +43,9 @@
 import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Locale;
+import java.util.Locale.LanguageRange;
 import java.util.Map;
+import java.util.Map.Entry;
 import java.util.Objects;
 import java.util.Optional;
 import java.util.Set;
@@ -111,6 +113,7 @@
 import org.springdoc.core.utils.PropertyResolverUtils;
 import org.springdoc.core.utils.SpringDocAnnotationsUtils;
 import org.springdoc.core.utils.SpringDocUtils;
+import org.springdoc.core.versions.SpringDocVersionStrategy;
 
 import org.springframework.aop.support.AopUtils;
 import org.springframework.beans.factory.ObjectFactory;
@@ -369,7 +372,7 @@ protected OpenAPI getOpenApi(String serverBaseUrl, Locale locale) {
 						.filter(controller -> (AnnotationUtils.findAnnotation(controller.getValue().getClass(),
 								Hidden.class) == null))
 						.filter(controller -> !isHiddenRestControllers(controller.getValue().getClass()))
-						.collect(Collectors.toMap(Map.Entry::getKey, Map.Entry::getValue, (a1, a2) -> a1));
+						.collect(Collectors.toMap(Entry::getKey, Entry::getValue, (a1, a2) -> a1));
 
 				Map<String, Object> findControllerAdvice = openAPIService.getControllerAdviceMap();
 				if (OpenApiVersion.OPENAPI_3_1 == springDocConfigProperties.getApiDocs().getVersion()) {
@@ -434,7 +437,7 @@ private Locale selectLocale(Locale inputLocale) {
 		List<String> allowedLocales = springDocConfigProperties.getAllowedLocales();
 		if (!CollectionUtils.isEmpty(allowedLocales)) {
 			Locale bestMatchingAllowedLocale = Locale.lookup(
-					Locale.LanguageRange.parse(inputLocale.toLanguageTag()),
+					LanguageRange.parse(inputLocale.toLanguageTag()),
 					allowedLocales.stream().map(Locale::forLanguageTag).toList()
 			);
 
@@ -568,7 +571,9 @@ protected void calculatePath(HandlerMethod handlerMethod, RouterOperation router
 		String[] methodProduces = routerOperation.getProduces();
 		String[] headers = routerOperation.getHeaders();
 		Map<String, String> queryParams = routerOperation.getQueryParams();
-
+		SpringDocVersionStrategy springDocVersionStrategy = routerOperation.getSpringDocVersionStrategy();
+		if (springDocVersionStrategy != null)
+			queryParams = springDocVersionStrategy.updateQueryParams(queryParams);
 		Components components = openAPI.getComponents();
 		Paths paths = openAPI.getPaths();
 
@@ -590,7 +595,7 @@ protected void calculatePath(HandlerMethod handlerMethod, RouterOperation router
 			RequestMapping reqMappingClass = AnnotatedElementUtils.findMergedAnnotation(handlerMethod.getBeanType(),
 					RequestMapping.class);
 
-			MethodAttributes methodAttributes = new MethodAttributes(springDocConfigProperties.getDefaultConsumesMediaType(), springDocConfigProperties.getDefaultProducesMediaType(), methodConsumes, methodProduces, headers, locale);
+			MethodAttributes methodAttributes = new MethodAttributes(springDocConfigProperties.getDefaultConsumesMediaType(), springDocConfigProperties.getDefaultProducesMediaType(), methodConsumes, methodProduces, headers, springDocVersionStrategy, locale);
 			methodAttributes.setMethodOverloaded(existingOperation != null);
 			//Use the javadoc return if present
 			if (javadocProvider != null) {
@@ -655,7 +660,7 @@ protected void calculatePath(HandlerMethod handlerMethod, RouterOperation router
 				}
 			}
 
-			Set<io.swagger.v3.oas.annotations.callbacks.Callback> apiCallbacks = AnnotatedElementUtils.findMergedRepeatableAnnotations(method, io.swagger.v3.oas.annotations.callbacks.Callback.class);
+			Set<Callback> apiCallbacks = AnnotatedElementUtils.findMergedRepeatableAnnotations(method, Callback.class);
 
 			// callbacks
 			buildCallbacks(openAPI, methodAttributes, operation, apiCallbacks);
@@ -757,7 +762,9 @@ protected void calculatePath(RouterOperation routerOperation, Locale locale, Ope
 		String[] methodProduces = routerOperation.getProduces();
 		String[] headers = routerOperation.getHeaders();
 		Map<String, String> queryParams = routerOperation.getQueryParams();
-
+		SpringDocVersionStrategy springDocVersionStrategy = routerOperation.getSpringDocVersionStrategy();
+		if(springDocVersionStrategy != null)
+			queryParams = springDocVersionStrategy.updateQueryParams(queryParams);
 		Paths paths = openAPI.getPaths();
 		Map<HttpMethod, Operation> operationMap = null;
 		if (paths.containsKey(operationPath)) {
@@ -766,7 +773,7 @@ protected void calculatePath(RouterOperation routerOperation, Locale locale, Ope
 		}
 		for (RequestMethod requestMethod : routerOperation.getMethods()) {
 			Operation existingOperation = getExistingOperation(operationMap, requestMethod);
-			MethodAttributes methodAttributes = new MethodAttributes(springDocConfigProperties.getDefaultConsumesMediaType(), springDocConfigProperties.getDefaultProducesMediaType(), methodConsumes, methodProduces, headers, locale);
+			MethodAttributes methodAttributes = new MethodAttributes(springDocConfigProperties.getDefaultConsumesMediaType(), springDocConfigProperties.getDefaultProducesMediaType(), methodConsumes, methodProduces, headers, springDocVersionStrategy, locale);
 			methodAttributes.setMethodOverloaded(existingOperation != null);
 			Operation operation = getOperation(routerOperation, existingOperation);
 			if (apiOperation != null)
@@ -812,19 +819,20 @@ private RouterOperation customizeDataRestRouterOperation(RouterOperation routerO
 	/**
 	 * Calculate path.
 	 *
-	 * @param handlerMethod  the handler method
-	 * @param operationPath  the operation path
-	 * @param requestMethods the request methods
-	 * @param consumes       the consumes
-	 * @param produces       the produces
-	 * @param headers        the headers
-	 * @param params         the params
-	 * @param locale         the locale
-	 * @param openAPI        the open api
+	 * @param handlerMethod   the handler method
+	 * @param operationPath   the operation path
+	 * @param requestMethods  the request methods
+	 * @param consumes        the consumes
+	 * @param produces        the produces
+	 * @param headers         the headers
+	 * @param params          the params
+	 * @param versionStrategy the version strategy
+	 * @param locale          the locale
+	 * @param openAPI         the open api
 	 */
 	protected void calculatePath(HandlerMethod handlerMethod, String operationPath,
-			Set<RequestMethod> requestMethods, String[] consumes, String[] produces, String[] headers, String[] params, Locale locale, OpenAPI openAPI) {
-		this.calculatePath(handlerMethod, new RouterOperation(operationPath, requestMethods.toArray(new RequestMethod[requestMethods.size()]), consumes, produces, headers, params), locale, openAPI);
+			Set<RequestMethod> requestMethods, String[] consumes, String[] produces, String[] headers, String[] params, SpringDocVersionStrategy versionStrategy, Locale locale, OpenAPI openAPI) {
+		this.calculatePath(handlerMethod, new RouterOperation(operationPath, requestMethods.toArray(new RequestMethod[requestMethods.size()]), consumes, produces, headers, params, versionStrategy), locale, openAPI);
 	}
 
 	/**
@@ -1227,10 +1235,16 @@ private void fillParametersList(Operation operation, Map<String, String> queryPa
 			}
 		});
 		if (!CollectionUtils.isEmpty(queryParams)) {
-			for (Map.Entry<String, String> entry : queryParams.entrySet()) {
-				io.swagger.v3.oas.models.parameters.Parameter parameter = new io.swagger.v3.oas.models.parameters.Parameter();
-				parameter.setName(entry.getKey());
-				parameter.setSchema(new StringSchema()._default(entry.getValue()));
+			Map<String, String> versionDefaultMap = null;
+			if(methodAttributes.getSpringDocVersionStrategy() != null)
+				versionDefaultMap= methodAttributes.getSpringDocVersionStrategy().getVersionDefaultMap();
+			for (Entry<String, String> entry : queryParams.entrySet()) {
+				Parameter parameter = new Parameter();
+				String name = entry.getKey();
+				String value = entry.getValue();
+				String defaultValue = (versionDefaultMap != null) ? versionDefaultMap.get(name) : value;
+				parameter.setName(name);
+				parameter.setSchema(new StringSchema()._default(defaultValue)._enum(Collections.singletonList(value)));
 				parameter.setRequired(true);
 				parameter.setIn(ParameterIn.QUERY.toString());
 				GenericParameterService.mergeParameter(parametersList, parameter);

springdoc-openapi-starter-common/src/main/java/org/springdoc/core/customizers/QuerydslPredicateOperationCustomizer.java

@@ -54,11 +54,11 @@
 
 import org.springframework.core.MethodParameter;
 import org.springframework.core.ResolvableType;
+import org.springframework.data.core.TypeInformation;
 import org.springframework.data.querydsl.binding.QuerydslBinderCustomizer;
 import org.springframework.data.querydsl.binding.QuerydslBindings;
 import org.springframework.data.querydsl.binding.QuerydslBindingsFactory;
 import org.springframework.data.querydsl.binding.QuerydslPredicate;
-import org.springframework.data.util.TypeInformation;
 import org.springframework.util.CollectionUtils;
 import org.springframework.web.method.HandlerMethod;
 

springdoc-openapi-starter-common/src/main/java/org/springdoc/core/data/DataRestRouterOperationService.java

@@ -285,7 +285,7 @@ else if (ControllerType.PROPERTY.equals(controllerType))
 			MethodResourceMapping methodResourceMapping, HandlerMethod handlerMethod,
 			RequestMethod requestMethod, ResourceMetadata resourceMetadata, String
 			operationPath, ControllerType controllerType) {
-		RouterOperation routerOperation = new RouterOperation(operationPath, new RequestMethod[] { requestMethod }, null, null, null, null);
+		RouterOperation routerOperation = new RouterOperation(operationPath, new RequestMethod[] { requestMethod }, null, null, null, null,null);
 		MethodAttributes methodAttributes = new MethodAttributes(springDocConfigProperties.getDefaultConsumesMediaType(), springDocConfigProperties.getDefaultProducesMediaType(), dataRestRepository.getLocale());
 		methodAttributes.calculateConsumesProduces(handlerMethod.getMethod());
 		routerOperation.setConsumes(methodAttributes.getMethodConsumes());

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

@@ -35,6 +35,7 @@
 import org.apache.commons.lang3.ArrayUtils;
 import org.apache.commons.lang3.StringUtils;
 import org.springdoc.core.fn.builders.operation.Builder;
+import org.springdoc.core.versions.SpringDocVersionStrategy;
 
 import org.springframework.web.bind.annotation.RequestMethod;
 
@@ -107,6 +108,11 @@ public class RouterOperation implements Comparable<RouterOperation> {
 	 */
 	private io.swagger.v3.oas.models.Operation operationModel;
 
+	/**
+	 * The Spring doc version strategy.
+	 */
+	private SpringDocVersionStrategy springDocVersionStrategy;
+
 	/**
 	 * Instantiates a new Router operation.
 	 */
@@ -154,20 +160,22 @@ public RouterOperation(org.springdoc.core.annotations.RouterOperation routerOper
 	/**
 	 * Instantiates a new Router operation.
 	 *
-	 * @param path     the path
-	 * @param methods  the methods
-	 * @param consumes the consumes
-	 * @param produces the produces
-	 * @param headers  the headers
-	 * @param params   the params
-	 */
-	public RouterOperation(String path, RequestMethod[] methods, String[] consumes, String[] produces, String[] headers, String[] params) {
+	 * @param path            the path
+	 * @param methods         the methods
+	 * @param consumes        the consumes
+	 * @param produces        the produces
+	 * @param headers         the headers
+	 * @param params          the params
+	 * @param springDocVersionStrategy the version strategy
+	 */
+	public RouterOperation(String path, RequestMethod[] methods, String[] consumes, String[] produces, String[] headers, String[] params, SpringDocVersionStrategy springDocVersionStrategy) {
 		this.path = path;
 		this.methods = methods;
 		this.consumes = consumes;
 		this.produces = produces;
 		this.headers = headers;
 		this.params = params;
+		this.springDocVersionStrategy = springDocVersionStrategy;
 	}
 
 	/**
@@ -422,6 +430,24 @@ public void setOperationModel(io.swagger.v3.oas.models.Operation operationModel)
 		this.operationModel = operationModel;
 	}
 
+	/**
+	 * Gets version strategy.
+	 *
+	 * @return the version strategy
+	 */
+	public SpringDocVersionStrategy getSpringDocVersionStrategy() {
+		return springDocVersionStrategy;
+	}
+
+	/**
+	 * Sets version strategy.
+	 *
+	 * @param springDocVersionStrategy the version strategy
+	 */
+	public void setVersionStrategy(SpringDocVersionStrategy springDocVersionStrategy) {
+		this.springDocVersionStrategy = springDocVersionStrategy;
+	}
+
 	@Override
 	public int compareTo(RouterOperation routerOperation) {
 		int result = path.compareTo(routerOperation.getPath());