Fixes #3263 - strip null-key entries from component schema properties before serialization

When swagger-core resolves a @JsonUnwrapped bean property (e.g. Spring HATEOAS
EntityModel<T>), it uses JSON-based cloning internally. Schema.getName() is
@JsonIgnore, so the name is lost during cloning. These null-named schemas are
then inserted as null keys into the properties map, causing Jackson to throw
JsonMappingException: Null key for a Map not allowed in JSON when serializing
the OpenAPI document.

Add SpringDocUtils.removeNullKeySchemas(OpenAPI) which recursively removes any
null-key entry from every component schema properties map, and call it in
AbstractOpenApiResource.getOpenApi() after schema resolution and before the
user-facing customizers run.

Five unit tests added in SpringDocUtilsTest covering top-level null keys,
nested null keys, null OpenAPI, null components, and schemas with no properties.

Author: Shaveenblu

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

@@ -407,6 +407,8 @@ protected OpenAPI getOpenApi(String serverBaseUrl, Locale locale) {
 				if (springDocConfigProperties.isRemoveBrokenReferenceDefinitions())
 					this.removeBrokenReferenceDefinitions(openAPI);
 
+				SpringDocUtils.removeNullKeySchemas(openAPI);
+
 				// run the optional customizers
 				List<Server> servers = openAPI.getServers();
 				List<Server> serversCopy = cloneViaJson(servers,  new TypeReference<List<Server>>() {},  springDocProviders.jsonMapper());

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

@@ -37,6 +37,7 @@
 import com.fasterxml.jackson.databind.ObjectMapper;
 import io.swagger.v3.core.converter.AnnotatedType;
 import io.swagger.v3.core.util.PrimitiveType;
+import io.swagger.v3.oas.models.OpenAPI;
 import io.swagger.v3.oas.models.media.ComposedSchema;
 import io.swagger.v3.oas.models.media.Content;
 import io.swagger.v3.oas.models.media.Schema;
@@ -215,6 +216,41 @@ else if (types == null && "null".equals(addPropSchema.getType())) {
 		}
 	}
 
+	/**
+	 * Remove null-key entries from schema properties maps across all component schemas.
+	 * This is a defensive fix for a swagger-core issue where {@code @JsonUnwrapped}
+	 * bean properties (e.g. on Spring HATEOAS {@code EntityModel}) can produce schemas
+	 * whose name is {@code null} — because {@link io.swagger.v3.oas.models.media.Schema#getName()}
+	 * is annotated with {@code @JsonIgnore} and is lost during internal JSON round-trip clones
+	 * inside {@code ModelResolver}. Those null-named schemas are then inserted as null keys
+	 * into the properties map, causing Jackson to fail with:
+	 * <pre>JsonMappingException: Null key for a Map not allowed in JSON</pre>
+	 *
+	 * @param openAPI the OpenAPI document to sanitize; no-op if {@code null}
+	 */
+	public static void removeNullKeySchemas(OpenAPI openAPI) {
+		if (openAPI == null || openAPI.getComponents() == null
+				|| openAPI.getComponents().getSchemas() == null) {
+			return;
+		}
+		openAPI.getComponents().getSchemas().values()
+				.forEach(schema -> removeNullKeyFromSchemaProperties((Schema<?>) schema));
+	}
+
+	/**
+	 * Recursively remove null-key entries from the given schema's properties map.
+	 *
+	 * @param schema the schema to sanitize
+	 */
+	private static void removeNullKeyFromSchemaProperties(Schema<?> schema) {
+		if (schema == null || schema.getProperties() == null) {
+			return;
+		}
+		schema.getProperties().entrySet().removeIf(entry -> entry.getKey() == null);
+		schema.getProperties().values()
+				.forEach(prop -> removeNullKeyFromSchemaProperties((Schema<?>) prop));
+	}
+
 	/**
 	 * Handle schema types.
 	 *

springdoc-openapi-starter-common/src/test/java/org/springdoc/core/utils/SpringDocUtilsTest.java

@@ -0,0 +1,135 @@
+/*
+ *
+ *  *
+ *  *  *
+ *  *  *  *
+ *  *  *  *  * 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 org.springdoc.core.utils;
+
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+import io.swagger.v3.oas.models.Components;
+import io.swagger.v3.oas.models.OpenAPI;
+import io.swagger.v3.oas.models.media.Schema;
+import io.swagger.v3.oas.models.media.StringSchema;
+import org.junit.jupiter.api.Test;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * Unit tests for {@link SpringDocUtils}.
+ */
+class SpringDocUtilsTest {
+
+	/**
+	 * Verify that {@link SpringDocUtils#removeNullKeySchemas(OpenAPI)} strips null-key
+	 * entries from the top-level properties map of every component schema.
+	 *
+	 * <p>This is a regression guard for GitHub issue #3263: when swagger-core resolves
+	 * a {@code @JsonUnwrapped} property (e.g. from Spring HATEOAS {@code EntityModel}),
+	 * it can produce a schema whose {@code name} is {@code null} and then insert that
+	 * schema under a null key in the parent's properties map. Jackson subsequently
+	 * fails with {@code JsonMappingException: Null key for a Map not allowed in JSON}.
+	 */
+	@Test
+	void removeNullKeySchemas_removesNullKeyFromTopLevelSchemaProperties() {
+		// Arrange – build a component schema whose properties map has a null key entry
+		Schema<Object> parentSchema = new Schema<>();
+		Map<String, Schema> props = new LinkedHashMap<>();
+		props.put("name", new StringSchema());
+		props.put(null, new StringSchema());    // null key – the problematic entry
+		props.put("count", new StringSchema());
+		parentSchema.setProperties(props);
+
+		OpenAPI openAPI = new OpenAPI()
+				.components(new Components().addSchemas("MyDto", parentSchema));
+
+		// Act
+		SpringDocUtils.removeNullKeySchemas(openAPI);
+
+		// Assert
+		Map<String, Schema> result = openAPI.getComponents().getSchemas().get("MyDto").getProperties();
+		assertThat(result).containsOnlyKeys("name", "count");
+		assertThat(result).doesNotContainKey(null);
+	}
+
+	/**
+	 * Verify that null-key cleanup recurses into nested schema properties.
+	 */
+	@Test
+	void removeNullKeySchemas_removesNullKeyFromNestedSchemaProperties() {
+		// Arrange
+		Schema<Object> nestedSchema = new Schema<>();
+		Map<String, Schema> nestedProps = new LinkedHashMap<>();
+		nestedProps.put("field", new StringSchema());
+		nestedProps.put(null, new StringSchema());   // null key in nested schema
+		nestedSchema.setProperties(nestedProps);
+
+		Schema<Object> parentSchema = new Schema<>();
+		Map<String, Schema> parentProps = new LinkedHashMap<>();
+		parentProps.put("nested", nestedSchema);
+		parentSchema.setProperties(parentProps);
+
+		OpenAPI openAPI = new OpenAPI()
+				.components(new Components().addSchemas("Parent", parentSchema));
+
+		// Act
+		SpringDocUtils.removeNullKeySchemas(openAPI);
+
+		// Assert – nested null key is also gone
+		Schema<?> parentResult = openAPI.getComponents().getSchemas().get("Parent");
+		Schema<?> nestedResult = (Schema<?>) parentResult.getProperties().get("nested");
+		assertThat(nestedResult.getProperties()).containsOnlyKeys("field");
+		assertThat(nestedResult.getProperties()).doesNotContainKey(null);
+	}
+
+	/**
+	 * Verify that a {@code null} OpenAPI argument is handled gracefully (no NPE).
+	 */
+	@Test
+	void removeNullKeySchemas_toleratesNullOpenApi() {
+		SpringDocUtils.removeNullKeySchemas(null);
+		// no exception expected
+	}
+
+	/**
+	 * Verify that an OpenAPI with no components is handled gracefully.
+	 */
+	@Test
+	void removeNullKeySchemas_toleratesNullComponents() {
+		SpringDocUtils.removeNullKeySchemas(new OpenAPI());
+		// no exception expected
+	}
+
+	/**
+	 * Verify that schemas with no properties are handled gracefully.
+	 */
+	@Test
+	void removeNullKeySchemas_toleratesSchemaWithNoProperties() {
+		Schema<Object> emptySchema = new Schema<>();
+		OpenAPI openAPI = new OpenAPI()
+				.components(new Components().addSchemas("Empty", emptySchema));
+		SpringDocUtils.removeNullKeySchemas(openAPI);
+		// no exception expected, schema unchanged
+		assertThat(openAPI.getComponents().getSchemas().get("Empty").getProperties()).isNull();
+	}
+}