Fix #3275: prevent @Nullable $ref field from mutating shared component schema type

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

@@ -469,6 +469,7 @@ private static void handleComponentSchemaTypes(OpenAPI openAPI) {
 		}
 		for (Schema<?> schema : openAPI.getComponents().getSchemas().values()) {
 			SpringDocUtils.fixNullOnlyAdditionalProperties(schema);
+			SpringDocUtils.fixNullMutatedObjectSchema(schema);
 		}
 	}
 

springdoc-openapi-starter-common/src/main/java/org/springdoc/core/utils/SpringDocUtils.java

@@ -215,6 +215,36 @@ else if (types == null && "null".equals(addPropSchema.getType())) {
 		}
 	}
 
+	/**
+	 * Fix component schemas that have been incorrectly mutated to {@code type: "null"} when they
+	 * have properties, which indicates they should be {@code type: "object"}.
+	 *
+	 * <p>This can happen when {@code @Nullable} is applied to a field whose type is represented
+	 * as a {@code $ref} component schema. swagger-core may propagate the nullable marker onto
+	 * the shared component schema itself, corrupting it for all references. This method restores
+	 * such schemas to {@code type: "object"} based on the presence of {@code properties}.
+	 *
+	 * @param schema the schema to fix
+	 * @see <a href="https://github.com/springdoc/springdoc-openapi/issues/3275">Issue #3275</a>
+	 */
+	public static void fixNullMutatedObjectSchema(Schema<?> schema) {
+		if (schema == null || schema.getProperties() == null || schema.getProperties().isEmpty()) {
+			return;
+		}
+		Set<String> types = schema.getTypes();
+		boolean isNullOnly = (types != null && types.size() == 1 && types.contains("null"))
+				|| (types == null && "null".equals(schema.getType()));
+		if (isNullOnly) {
+			if (types != null) {
+				types.remove("null");
+				types.add("object");
+			}
+			else {
+				schema.setType("object");
+			}
+		}
+	}
+
 	/**
 	 * Handle schema types.
 	 *

springdoc-openapi-tests/pom.xml

@@ -2,7 +2,7 @@
 	<parent>
 		<artifactId>springdoc-openapi</artifactId>
 		<groupId>org.springdoc</groupId>
-		<version>2.8.17-SNAPSHOT</version>
+		<version>2.8.18-SNAPSHOT</version>
 	</parent>
 	<packaging>pom</packaging>
 	<modelVersion>4.0.0</modelVersion>

springdoc-openapi-tests/springdoc-openapi-actuator-webflux-tests/pom.xml

@@ -2,7 +2,7 @@
 	<parent>
 		<artifactId>springdoc-openapi-tests</artifactId>
 		<groupId>org.springdoc</groupId>
-		<version>2.8.17-SNAPSHOT</version>
+		<version>2.8.18-SNAPSHOT</version>
 	</parent>
 	<modelVersion>4.0.0</modelVersion>
 

springdoc-openapi-tests/springdoc-openapi-actuator-webmvc-tests/pom.xml

@@ -2,7 +2,7 @@
 	<parent>
 		<artifactId>springdoc-openapi-tests</artifactId>
 		<groupId>org.springdoc</groupId>
-		<version>2.8.17-SNAPSHOT</version>
+		<version>2.8.18-SNAPSHOT</version>
 	</parent>
 	<modelVersion>4.0.0</modelVersion>
 

springdoc-openapi-tests/springdoc-openapi-data-rest-tests/pom.xml

@@ -2,7 +2,7 @@
 	<parent>
 		<artifactId>springdoc-openapi-tests</artifactId>
 		<groupId>org.springdoc</groupId>
-		<version>2.8.17-SNAPSHOT</version>
+		<version>2.8.18-SNAPSHOT</version>
 	</parent>
 	<modelVersion>4.0.0</modelVersion>
 	<artifactId>springdoc-openapi-data-rest-tests</artifactId>

springdoc-openapi-tests/springdoc-openapi-function-webflux-tests/pom.xml

@@ -2,7 +2,7 @@
 	<parent>
 		<artifactId>springdoc-openapi-tests</artifactId>
 		<groupId>org.springdoc</groupId>
-		<version>2.8.17-SNAPSHOT</version>
+		<version>2.8.18-SNAPSHOT</version>
 	</parent>
 	<modelVersion>4.0.0</modelVersion>
 

springdoc-openapi-tests/springdoc-openapi-function-webmvc-tests/pom.xml

@@ -2,7 +2,7 @@
 	<parent>
 		<artifactId>springdoc-openapi-tests</artifactId>
 		<groupId>org.springdoc</groupId>
-		<version>2.8.17-SNAPSHOT</version>
+		<version>2.8.18-SNAPSHOT</version>
 	</parent>
 	<modelVersion>4.0.0</modelVersion>
 

springdoc-openapi-tests/springdoc-openapi-groovy-tests/pom.xml

@@ -3,7 +3,7 @@
 	<parent>
 		<groupId>org.springdoc</groupId>
 		<artifactId>springdoc-openapi-tests</artifactId>
-		<version>2.8.17-SNAPSHOT</version>
+		<version>2.8.18-SNAPSHOT</version>
 	</parent>
 	<artifactId>springdoc-openapi-groovy-tests</artifactId>
 	<name>${project.artifactId}</name>

springdoc-openapi-tests/springdoc-openapi-hateoas-tests/pom.xml

@@ -2,7 +2,7 @@
 	<parent>
 		<artifactId>springdoc-openapi-tests</artifactId>
 		<groupId>org.springdoc</groupId>
-		<version>2.8.17-SNAPSHOT</version>
+		<version>2.8.18-SNAPSHOT</version>
 	</parent>
 	<modelVersion>4.0.0</modelVersion>
 	<artifactId>springdoc-openapi-hateoas-tests</artifactId>

springdoc-openapi-tests/springdoc-openapi-javadoc-tests/pom.xml

@@ -2,7 +2,7 @@
 	<parent>
 		<groupId>org.springdoc</groupId>
 		<artifactId>springdoc-openapi-tests</artifactId>
-		<version>2.8.17-SNAPSHOT</version>
+		<version>2.8.18-SNAPSHOT</version>
 	</parent>
 	<modelVersion>4.0.0</modelVersion>
 

springdoc-openapi-tests/springdoc-openapi-javadoc-tests/src/test/java/test/org/springdoc/api/v31/app175/Inner.java

@@ -0,0 +1,37 @@
+/*
+ *
+ *  *
+ *  *  *
+ *  *  *  *
+ *  *  *  *  *
+ *  *  *  *  *  * 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.app175;
+
+/**
+ * Inner record used as a referenced component schema.
+ *
+ * @param lines the line count
+ * @param bytes the byte count
+ * @param bucket the bucket name
+ * @param key the object key
+ */
+public record Inner(int lines, long bytes, String bucket, String key) {}

springdoc-openapi-tests/springdoc-openapi-javadoc-tests/src/test/java/test/org/springdoc/api/v31/app175/NullableRefController.java

@@ -0,0 +1,49 @@
+/*
+ *
+ *  *
+ *  *  *
+ *  *  *  *
+ *  *  *  *  *
+ *  *  *  *  *  * 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.app175;
+
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+/**
+ * Controller for regression test of issue #3275.
+ * Verifies that a {@code @Nullable} field referencing a component schema does not
+ * mutate the referenced schema's type to {@code "null"}.
+ */
+@RestController
+class NullableRefController {
+
+	/**
+	 * Returns an Outer record with a nullable Inner reference.
+	 *
+	 * @return the outer record
+	 */
+	@GetMapping("/outer")
+	public Outer getOuter() {
+		return new Outer("x", null);
+	}
+}

springdoc-openapi-tests/springdoc-openapi-javadoc-tests/src/test/java/test/org/springdoc/api/v31/app175/Outer.java

@@ -0,0 +1,37 @@
+/*
+ *
+ *  *
+ *  *  *
+ *  *  *  *
+ *  *  *  *  *
+ *  *  *  *  *  * 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.app175;
+
+import org.springframework.lang.Nullable;
+
+/**
+ * Outer record with a nullable reference to {@link Inner}.
+ *
+ * @param id the identifier
+ * @param result the optional inner result, may be null
+ */
+public record Outer(String id, @Nullable Inner result) {}

springdoc-openapi-tests/springdoc-openapi-javadoc-tests/src/test/java/test/org/springdoc/api/v31/app175/SpringDocApp175Test.java

@@ -0,0 +1,46 @@
+/*
+ *
+ *  *
+ *  *  *
+ *  *  *  *
+ *  *  *  *  *
+ *  *  *  *  *  * 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.app175;
+
+import test.org.springdoc.api.v31.AbstractSpringDocTest;
+
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+/**
+ * Test for issue #3275: verifies that a {@code @Nullable} field referencing a component schema
+ * does not mutate the referenced schema's type to {@code "null"}.
+ */
+class SpringDocApp175Test extends AbstractSpringDocTest {
+
+	/**
+	 * The type Spring doc test app.
+	 */
+	@SpringBootApplication
+	static class SpringDocTestApp {
+	}
+
+}

springdoc-openapi-tests/springdoc-openapi-javadoc-tests/src/test/resources/results/3.1.0/app175.json

@@ -0,0 +1,69 @@
+{
+  "openapi": "3.1.0",
+  "info": {
+    "title": "OpenAPI definition",
+    "version": "v0"
+  },
+  "servers": [
+    {
+      "url": "http://localhost",
+      "description": "Generated server url"
+    }
+  ],
+  "paths": {
+    "/outer": {
+      "get": {
+        "tags": [
+          "nullable-ref-controller"
+        ],
+        "operationId": "getOuter",
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "*/*": {
+                "schema": {
+                  "$ref": "#/components/schemas/Outer"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "Inner": {
+        "type": "object",
+        "properties": {
+          "lines": {
+            "type": "integer",
+            "format": "int32"
+          },
+          "bytes": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "bucket": {
+            "type": "string"
+          },
+          "key": {
+            "type": "string"
+          }
+        }
+      },
+      "Outer": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "result": {
+            "$ref": "#/components/schemas/Inner"
+          }
+        }
+      }
+    }
+  }
+}

springdoc-openapi-tests/springdoc-openapi-kotlin-webflux-tests/pom.xml

@@ -2,7 +2,7 @@
 	<parent>
 		<artifactId>springdoc-openapi-tests</artifactId>
 		<groupId>org.springdoc</groupId>
-		<version>2.8.17-SNAPSHOT</version>
+		<version>2.8.18-SNAPSHOT</version>
 	</parent>
 	<modelVersion>4.0.0</modelVersion>
 	<artifactId>springdoc-openapi-kotlin-webflux-tests</artifactId>

springdoc-openapi-tests/springdoc-openapi-kotlin-webmvc-tests/pom.xml

@@ -2,7 +2,7 @@
 	<parent>
 		<artifactId>springdoc-openapi-tests</artifactId>
 		<groupId>org.springdoc</groupId>
-		<version>2.8.17-SNAPSHOT</version>
+		<version>2.8.18-SNAPSHOT</version>
 	</parent>
 	<modelVersion>4.0.0</modelVersion>
 	<artifactId>springdoc-openapi-kotlin-webmvc-tests</artifactId>