Setting API Version Required when using WebFlux breaks the Swagger UI. Fixes #3258

Author: bnasslahsen

springdoc-openapi-starter-webflux-api/src/main/java/org/springdoc/webflux/api/SpringDocApiVersionStrategy.java

@@ -33,6 +33,7 @@
 import reactor.core.publisher.Mono;
 
 import org.springframework.web.accept.InvalidApiVersionException;
+import org.springframework.web.accept.MissingApiVersionException;
 import org.springframework.web.reactive.accept.ApiVersionStrategy;
 import org.springframework.web.server.ServerWebExchange;
 
@@ -66,6 +67,12 @@ public SpringDocApiVersionStrategy(ApiVersionStrategy delegate, List<String> spr
 			return delegate.resolveParseAndValidateVersion(exchange);
 		}
 		catch (InvalidApiVersionException ex) {
+			if (isSpringDocPath(exchange)) {
+				return resolveVersionForSpringDocPath(ex);
+			}
+			throw ex;
+		}
+		catch (MissingApiVersionException ex) {
 			if (isSpringDocPath(exchange)) {
 				return delegate.getDefaultVersion();
 			}
@@ -76,15 +83,40 @@ public SpringDocApiVersionStrategy(ApiVersionStrategy delegate, List<String> spr
 	@Override
 	public Mono<Comparable<?>> resolveParseAndValidateApiVersion(ServerWebExchange exchange) {
 		return delegate.resolveParseAndValidateApiVersion(exchange)
-				.onErrorResume(InvalidApiVersionException.class, ex -> {
+				.onErrorResume(ex -> {
 					if (isSpringDocPath(exchange)) {
-						Comparable<?> defaultVersion = delegate.getDefaultVersion();
-						return defaultVersion != null ? Mono.just(defaultVersion) : Mono.empty();
+						if (ex instanceof InvalidApiVersionException invalidEx) {
+							return Mono.just(resolveVersionForSpringDocPath(invalidEx));
+						}
+						else if (ex instanceof MissingApiVersionException) {
+							Comparable<?> defaultVersion = delegate.getDefaultVersion();
+							return defaultVersion != null ? Mono.just(defaultVersion) : Mono.just((Comparable<?>) "");
+						}
 					}
 					return Mono.error(ex);
 				});
 	}
 
+	/**
+	 * Resolve a version for springdoc paths when validation fails.
+	 * <p>Re-parses the invalid version string without validation, since springdoc
+	 * endpoints have no version condition and will match any version. This ensures
+	 * a non-null value is returned, which is required for the reactive handler
+	 * mapping to proceed with handler lookup.
+	 *
+	 * @param ex the invalid API version exception
+	 * @return the parsed version, or the default version as fallback
+	 */
+	private Comparable<?> resolveVersionForSpringDocPath(InvalidApiVersionException ex) {
+		try {
+			return delegate.parseVersion(ex.getVersion());
+		}
+		catch (Exception parseEx) {
+			Comparable<?> defaultVersion = delegate.getDefaultVersion();
+			return defaultVersion != null ? defaultVersion : (Comparable<?>) ex.getVersion();
+		}
+	}
+
 	@Override
 	public @Nullable String resolveVersion(ServerWebExchange exchange) {
 		return delegate.resolveVersion(exchange);

springdoc-openapi-starter-webflux-api/src/test/java/test/org/springdoc/api/v31/app203/SpringDocApp203Test.java

@@ -0,0 +1,44 @@
+/*
+ *
+ *  *
+ *  *  *
+ *  *  *  *
+ *  *  *  *  *
+ *  *  *  *  *  * Copyright 2019-2026 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.app203;
+
+import test.org.springdoc.api.v31.AbstractSpringDocTest;
+
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+import org.springframework.context.annotation.ComponentScan;
+
+/**
+ * Test for path-based API versioning with versionRequired=true and no default version.
+ *
+ * @author bnasslahsen
+ */
+public class SpringDocApp203Test extends AbstractSpringDocTest {
+
+	@SpringBootApplication
+	@ComponentScan(basePackages = { "org.springdoc", "test.org.springdoc.api.v31.app203" })
+	static class SpringDocTestApp {}
+}

springdoc-openapi-starter-webflux-api/src/test/java/test/org/springdoc/api/v31/app203/config/ApiVersionParser.java

@@ -0,0 +1,18 @@
+package test.org.springdoc.api.v31.app203.config;
+
+/**
+ * @author bnasslahsen
+ */
+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);
+		}
+		return version;
+	}
+
+}

springdoc-openapi-starter-webflux-api/src/test/java/test/org/springdoc/api/v31/app203/config/WebConfig.java

@@ -0,0 +1,23 @@
+package test.org.springdoc.api.v31.app203.config;
+
+import org.springframework.context.annotation.Configuration;
+import org.springframework.web.reactive.config.ApiVersionConfigurer;
+import org.springframework.web.reactive.config.WebFluxConfigurer;
+
+/**
+ * @author bnasslahsen
+ */
+@Configuration
+public class WebConfig implements WebFluxConfigurer {
+
+	@Override
+	public void configureApiVersioning(ApiVersionConfigurer configurer) {
+		configurer
+				.usePathSegment(1)
+				.detectSupportedVersions(false)
+				.addSupportedVersions("1.0", "2.0")
+				.setVersionRequired(true)
+				.setVersionParser(new ApiVersionParser());
+	}
+
+}

springdoc-openapi-starter-webflux-api/src/test/java/test/org/springdoc/api/v31/app203/user/User.java

@@ -0,0 +1,8 @@
+package test.org.springdoc.api.v31.app203.user;
+
+public record User(
+        Integer id,
+        String name,
+        String email
+) {
+}

springdoc-openapi-starter-webflux-api/src/test/java/test/org/springdoc/api/v31/app203/user/UserController.java

@@ -0,0 +1,35 @@
+package test.org.springdoc.api.v31.app203.user;
+
+import java.util.List;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+@RestController
+@RequestMapping("/api")
+public class UserController {
+
+    private static final Logger log = LoggerFactory.getLogger(UserController.class);
+    private final UserRepository userRepository;
+
+    public UserController(UserRepository userRepository) {
+        this.userRepository = userRepository;
+    }
+
+	@GetMapping(value = "/{version}/users", version = "1.0")
+	public List<User> findAllv1() {
+		log.info("Finding all users v1");
+		return userRepository.findAll();
+	}
+
+	@GetMapping(value = "/{version}/users", version = "2.0")
+	public List<User> findAllv2() {
+		log.info("Finding all users v2");
+		return userRepository.findAll();
+	}
+
+}

springdoc-openapi-starter-webflux-api/src/test/java/test/org/springdoc/api/v31/app203/user/UserRepository.java

@@ -0,0 +1,23 @@
+package test.org.springdoc.api.v31.app203.user;
+
+import java.util.ArrayList;
+import java.util.List;
+
+import jakarta.annotation.PostConstruct;
+
+import org.springframework.stereotype.Repository;
+
+@Repository
+public class UserRepository {
+
+    private final List<User> users = new ArrayList<>();
+
+    public List<User> findAll() {
+        return users;
+    }
+
+    @PostConstruct
+    private void init() {
+        users.add(new User(1,"Dan Vega","danvega@gmail.com"));
+    }
+}

springdoc-openapi-starter-webflux-api/src/test/resources/results/3.1.0/app203.json

@@ -0,0 +1,80 @@
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "OpenAPI definition",
+    "version": "v0"
+  },
+  "servers": [
+    {
+      "url": "",
+      "description": "Generated server url"
+    }
+  ],
+  "paths": {
+    "/api/2.0/users": {
+      "get": {
+        "tags": [
+          "user-controller"
+        ],
+        "operationId": "findAllv2",
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "*/*": {
+                "schema": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/components/schemas/User"
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/api/1.0/users": {
+      "get": {
+        "tags": [
+          "user-controller"
+        ],
+        "operationId": "findAllv1",
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "*/*": {
+                "schema": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/components/schemas/User"
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "User": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "integer",
+            "format": "int32"
+          },
+          "name": {
+            "type": "string"
+          },
+          "email": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}

springdoc-openapi-starter-webmvc-api/src/main/java/org/springdoc/webmvc/api/SpringDocApiVersionStrategy.java

@@ -35,6 +35,7 @@
 
 import org.springframework.web.accept.ApiVersionStrategy;
 import org.springframework.web.accept.InvalidApiVersionException;
+import org.springframework.web.accept.MissingApiVersionException;
 
 /**
  * Servlet-based delegating {@link ApiVersionStrategy} that gracefully handles springdoc endpoint paths.
@@ -66,13 +67,36 @@ public SpringDocApiVersionStrategy(ApiVersionStrategy delegate, List<String> spr
 			return delegate.resolveParseAndValidateVersion(request);
 		}
 		catch (InvalidApiVersionException ex) {
+			if (isSpringDocPath(request)) {
+				return resolveVersionForSpringDocPath(ex);
+			}
+			throw ex;
+		}
+		catch (MissingApiVersionException ex) {
 			if (isSpringDocPath(request)) {
 				return delegate.getDefaultVersion();
 			}
 			throw ex;
 		}
 	}
 
+	/**
+	 * Resolve a version for springdoc paths when validation fails.
+	 * <p>Re-parses the invalid version string without validation, since springdoc
+	 * endpoints have no version condition and will match any version.
+	 *
+	 * @param ex the invalid API version exception
+	 * @return the parsed version, or the default version as fallback
+	 */
+	private @Nullable Comparable<?> resolveVersionForSpringDocPath(InvalidApiVersionException ex) {
+		try {
+			return delegate.parseVersion(ex.getVersion());
+		}
+		catch (Exception parseEx) {
+			return delegate.getDefaultVersion();
+		}
+	}
+
 	@Override
 	public @Nullable String resolveVersion(HttpServletRequest request) {
 		return delegate.resolveVersion(request);