Merge backport of #3323/#3321, #3317 and the Spring Data REST response fixes

Backports to the Spring Boot 3 line:
- #3323 / #3321 - login endpoint example values
- #3317 - ignore an injected HttpHeaders parameter
- the shared-schema fix on top of the #3136 backport

Author: bnasslahsen

CHANGELOG.md

@@ -16,6 +16,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - #3340 – Describe `JsonNullable` values without their Java wrapper
 - #3325 – Manage the swagger artifacts in `springdoc-openapi-bom`, so that modules holding only the annotations stay in lockstep
+- #3321 – Add `springdoc.login-endpoint.username-example` and `springdoc.login-endpoint.password-example` to document the Spring Security login endpoint
 
 ### Changed
 
@@ -39,6 +40,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - #3338 – Kotlin nullability interpretation of the `Any?` type
 - #3332 – The properties a Kotlin entity inherits from an `@Embeddable` are missing from the Spring Data REST schemas
 - #3136 – A Spring Data REST association to a non-exported entity expands its `@EmbeddedId` and `@MapsId` fields recursively in the response schemas
+- The Spring Data REST response post-processing rewrote an association property in place, so the `…Response` refs could leak into the schema shared with the request body representation
+- #3317 – Ignore an injected `HttpHeaders` parameter explicitly. The reported failure needs Spring Framework 7, where `HttpHeaders` stopped implementing `MultiValueMap`; on this line it is still covered by the `Map` entry of the ignore list, so this is regression cover rather than a behaviour change
+- Harden the Spring Data REST response post-processing against an `_embedded` schema that carries no properties
 
 ## [2.9.0] - 2026-07-31
 

springdoc-openapi-starter-common/src/main/java/org/springdoc/core/configuration/SpringDocSecurityConfiguration.java

@@ -45,6 +45,8 @@
 import org.springdoc.core.configuration.hints.SpringDocSecurityHints;
 import org.springdoc.core.customizers.GlobalOpenApiCustomizer;
 import org.springdoc.core.customizers.OpenApiCustomizer;
+import org.springdoc.core.properties.SpringDocConfigProperties;
+import org.springdoc.core.properties.SpringDocConfigProperties.LoginEndpoint;
 
 import org.springframework.boot.autoconfigure.AutoConfigureAfter;
 import org.springframework.boot.autoconfigure.condition.ConditionalOnBean;
@@ -113,14 +115,18 @@ class SpringSecurityLoginEndpointConfiguration {
 		/**
 		 * Spring security login endpoint customiser open api customiser.
 		 *
-		 * @param applicationContext the application context
+		 * @param applicationContext        the application context
+		 * @param springDocConfigProperties the springdoc configuration properties
 		 * @return the open api customiser
 		 */
 		@Bean
 		@ConditionalOnProperty(SPRINGDOC_SHOW_LOGIN_ENDPOINT)
 		@Lazy(false)
-		OpenApiCustomizer springSecurityLoginEndpointCustomizer(ApplicationContext applicationContext) {
+		OpenApiCustomizer springSecurityLoginEndpointCustomizer(ApplicationContext applicationContext, SpringDocConfigProperties springDocConfigProperties) {
 			FilterChainProxy filterChainProxy = applicationContext.getBean(AbstractSecurityWebApplicationInitializer.DEFAULT_FILTER_NAME, FilterChainProxy.class);
+			LoginEndpoint loginEndpoint = springDocConfigProperties.getLoginEndpoint();
+			String usernameExample = loginEndpoint.getUsernameExample();
+			String passwordExample = loginEndpoint.getPasswordExample();
 			return openAPI -> {
 				for (SecurityFilterChain filterChain : filterChainProxy.getFilterChains()) {
 					Optional<UsernamePasswordAuthenticationFilter> optionalFilter =
@@ -135,29 +141,8 @@ OpenApiCustomizer springSecurityLoginEndpointCustomizer(ApplicationContext appli
 									.findAny();
 					if (optionalFilter.isPresent()) {
 						UsernamePasswordAuthenticationFilter usernamePasswordAuthenticationFilter = optionalFilter.get();
-						Operation operation = new Operation();
-						Schema<?> schema = new ObjectSchema()
-								.addProperty(usernamePasswordAuthenticationFilter.getUsernameParameter(), new StringSchema())
-								.addProperty(usernamePasswordAuthenticationFilter.getPasswordParameter(), new StringSchema());
-						String mediaType = org.springframework.http.MediaType.APPLICATION_JSON_VALUE;
-						if (optionalDefaultLoginPageGeneratingFilter.isPresent()) {
-							DefaultLoginPageGeneratingFilter defaultLoginPageGeneratingFilter = optionalDefaultLoginPageGeneratingFilter.get();
-							try {
-								boolean formLoginEnabled = (boolean) FieldUtils.readDeclaredField(defaultLoginPageGeneratingFilter, "formLoginEnabled", true);
-								if (formLoginEnabled)
-									mediaType = org.springframework.http.MediaType.APPLICATION_FORM_URLENCODED_VALUE;
-							}
-							catch (IllegalAccessException e) {
-								LOGGER.warn(e.getMessage());
-							}
-						}
-						RequestBody requestBody = new RequestBody().content(new Content().addMediaType(mediaType, new MediaType().schema(schema)));
-						operation.requestBody(requestBody);
-						ApiResponses apiResponses = new ApiResponses();
-						apiResponses.addApiResponse(String.valueOf(HttpStatus.OK.value()), new ApiResponse().description(HttpStatus.OK.getReasonPhrase()));
-						apiResponses.addApiResponse(String.valueOf(HttpStatus.UNAUTHORIZED.value()), new ApiResponse().description(HttpStatus.UNAUTHORIZED.getReasonPhrase()));
-						operation.responses(apiResponses);
-						operation.addTagsItem("login-endpoint");
+						String mediaType = resolveMediaType(optionalDefaultLoginPageGeneratingFilter);
+						Operation operation = buildOperation(usernamePasswordAuthenticationFilter, mediaType, usernameExample, passwordExample);
 						PathItem pathItem = new PathItem().post(operation);
 						try {
 							RequestMatcher requestMatcher = (RequestMatcher) FieldUtils.readField(
@@ -191,6 +176,81 @@ else if (requestMatcher instanceof PathPatternRequestMatcher) {
 				}
 			};
 		}
+
+		/**
+		 * Resolves the request body media type based on the presence of a form login configuration.
+		 *
+		 * @param optionalDefaultLoginPageGeneratingFilter the optional default login page generating filter
+		 * @return the resolved media type
+		 */
+		private String resolveMediaType(Optional<DefaultLoginPageGeneratingFilter> optionalDefaultLoginPageGeneratingFilter) {
+			String mediaType = org.springframework.http.MediaType.APPLICATION_JSON_VALUE;
+			if (optionalDefaultLoginPageGeneratingFilter.isPresent()) {
+				DefaultLoginPageGeneratingFilter defaultLoginPageGeneratingFilter = optionalDefaultLoginPageGeneratingFilter.get();
+				try {
+					boolean formLoginEnabled = (boolean) FieldUtils.readDeclaredField(defaultLoginPageGeneratingFilter, "formLoginEnabled", true);
+					if (formLoginEnabled)
+						mediaType = org.springframework.http.MediaType.APPLICATION_FORM_URLENCODED_VALUE;
+				}
+				catch (IllegalAccessException e) {
+					LOGGER.warn(e.getMessage());
+				}
+			}
+			return mediaType;
+		}
+
+		/**
+		 * Builds the login endpoint operation.
+		 *
+		 * @param usernamePasswordAuthenticationFilter the username password authentication filter
+		 * @param mediaType                            the request body media type
+		 * @param usernameExample                      the username example value
+		 * @param passwordExample                      the password example value
+		 * @return the operation
+		 */
+		private Operation buildOperation(UsernamePasswordAuthenticationFilter usernamePasswordAuthenticationFilter,
+				String mediaType, String usernameExample, String passwordExample) {
+			Operation operation = new Operation();
+			operation.requestBody(buildRequestBody(usernamePasswordAuthenticationFilter, mediaType, usernameExample, passwordExample));
+			operation.responses(buildApiResponses());
+			operation.addTagsItem("login-endpoint");
+			return operation;
+		}
+
+		/**
+		 * Builds the request body for the login endpoint operation.
+		 *
+		 * @param usernamePasswordAuthenticationFilter the username password authentication filter
+		 * @param mediaType                            the request body media type
+		 * @param usernameExample                      the username example value
+		 * @param passwordExample                      the password example value
+		 * @return the request body
+		 */
+		private RequestBody buildRequestBody(UsernamePasswordAuthenticationFilter usernamePasswordAuthenticationFilter,
+				String mediaType, String usernameExample, String passwordExample) {
+			StringSchema usernameSchema = new StringSchema();
+			if (usernameExample != null)
+				usernameSchema.example(usernameExample);
+			StringSchema passwordSchema = new StringSchema();
+			if (passwordExample != null)
+				passwordSchema.example(passwordExample);
+			Schema<?> schema = new ObjectSchema()
+					.addProperty(usernamePasswordAuthenticationFilter.getUsernameParameter(), usernameSchema)
+					.addProperty(usernamePasswordAuthenticationFilter.getPasswordParameter(), passwordSchema);
+			return new RequestBody().content(new Content().addMediaType(mediaType, new MediaType().schema(schema)));
+		}
+
+		/**
+		 * Builds the API responses for the login endpoint operation.
+		 *
+		 * @return the api responses
+		 */
+		private ApiResponses buildApiResponses() {
+			ApiResponses apiResponses = new ApiResponses();
+			apiResponses.addApiResponse(String.valueOf(HttpStatus.OK.value()), new ApiResponse().description(HttpStatus.OK.getReasonPhrase()));
+			apiResponses.addApiResponse(String.valueOf(HttpStatus.UNAUTHORIZED.value()), new ApiResponse().description(HttpStatus.UNAUTHORIZED.getReasonPhrase()));
+			return apiResponses;
+		}
 	}
 
 	/**

springdoc-openapi-starter-common/src/main/java/org/springdoc/core/properties/SpringDocConfigProperties.java

@@ -168,6 +168,11 @@ public class SpringDocConfigProperties {
 	 */
 	private boolean showLoginEndpoint;
 
+	/**
+	 * The login endpoint configuration.
+	 */
+	private LoginEndpoint loginEndpoint = new LoginEndpoint();
+
 	/**
 	 * Allow for pre-loading OpenAPI
 	 */
@@ -749,6 +754,24 @@ public void setShowLoginEndpoint(boolean showLoginEndpoint) {
 		this.showLoginEndpoint = showLoginEndpoint;
 	}
 
+	/**
+	 * Gets login endpoint.
+	 *
+	 * @return the login endpoint
+	 */
+	public LoginEndpoint getLoginEndpoint() {
+		return loginEndpoint;
+	}
+
+	/**
+	 * Sets login endpoint.
+	 *
+	 * @param loginEndpoint the login endpoint
+	 */
+	public void setLoginEndpoint(LoginEndpoint loginEndpoint) {
+		this.loginEndpoint = loginEndpoint;
+	}
+
 	/**
 	 * Gets packages to scan.
 	 *
@@ -1984,4 +2007,61 @@ public int hashCode() {
 			return Objects.hash(group);
 		}
 	}
+
+	/**
+	 * The type Login endpoint.
+	 * <p>
+	 * These settings only take effect when the login endpoint is exposed, i.e. when
+	 * {@code springdoc.show-login-endpoint=true}. Otherwise, they are ignored.
+	 */
+	public static class LoginEndpoint {
+
+		/**
+		 * The example value for the username field of the login request body.
+		 * Only applied when {@code springdoc.show-login-endpoint=true}.
+		 */
+		private String usernameExample;
+
+		/**
+		 * The example value for the password field of the login request body.
+		 * Only applied when {@code springdoc.show-login-endpoint=true}.
+		 */
+		private String passwordExample;
+
+		/**
+		 * Gets username example.
+		 *
+		 * @return the username example
+		 */
+		public String getUsernameExample() {
+			return usernameExample;
+		}
+
+		/**
+		 * Sets username example.
+		 *
+		 * @param usernameExample the username example
+		 */
+		public void setUsernameExample(String usernameExample) {
+			this.usernameExample = usernameExample;
+		}
+
+		/**
+		 * Gets password example.
+		 *
+		 * @return the password example
+		 */
+		public String getPasswordExample() {
+			return passwordExample;
+		}
+
+		/**
+		 * Sets password example.
+		 *
+		 * @param passwordExample the password example
+		 */
+		public void setPasswordExample(String passwordExample) {
+			this.passwordExample = passwordExample;
+		}
+	}
 }

springdoc-openapi-starter-common/src/main/java/org/springdoc/core/service/AbstractRequestService.java

@@ -75,6 +75,7 @@
 
 import org.springframework.core.MethodParameter;
 import org.springframework.core.annotation.AnnotatedElementUtils;
+import org.springframework.http.HttpHeaders;
 import org.springframework.http.HttpMethod;
 import org.springframework.ui.Model;
 import org.springframework.ui.ModelMap;
@@ -122,6 +123,7 @@ public abstract class AbstractRequestService {
 		PARAM_TYPES_TO_IGNORE.add(NativeWebRequest.class);
 		PARAM_TYPES_TO_IGNORE.add(Principal.class);
 		PARAM_TYPES_TO_IGNORE.add(HttpMethod.class);
+		PARAM_TYPES_TO_IGNORE.add(HttpHeaders.class);
 		PARAM_TYPES_TO_IGNORE.add(Locale.class);
 		PARAM_TYPES_TO_IGNORE.add(TimeZone.class);
 		PARAM_TYPES_TO_IGNORE.add(InputStream.class);

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

@@ -39,6 +39,7 @@
 import io.swagger.v3.core.converter.AnnotatedType;
 import io.swagger.v3.core.converter.ModelConverters;
 import io.swagger.v3.core.converter.ResolvedSchema;
+import io.swagger.v3.core.util.AnnotationsUtils;
 import io.swagger.v3.oas.models.Components;
 import io.swagger.v3.oas.models.OpenAPI;
 import io.swagger.v3.oas.models.PathItem;
@@ -288,7 +289,11 @@ else if (EMBEDDED.equals(propId)) {
 					updateResponseSchemaEmbedded(components, entityInfo, entry, openapi31);
 				}
 				else if (allAssociationsFieldsMap.getOrDefault(className, Collections.emptySet()).contains(propId)) {
-					updateResponseSchemaProperty(entry.getValue(), components, openapi31);
+					// the property schema may be shared with the request body representation,
+					// so rewrite a copy of it instead of the resolved instance
+					Schema propertyCopy = AnnotationsUtils.clone(entry.getValue(), openapi31);
+					updateResponseSchemaProperty(propertyCopy, components, openapi31);
+					entry.setValue(propertyCopy);
 				}
 			}
 		}
@@ -334,15 +339,16 @@ else if (property.getItems() != null) {
 	 */
 	private void updateResponseSchemaEmbedded(Components components, EntityInfo entityInfo, Entry<String, Schema> entry, boolean openapi31) {
 		String entityClassName = linkRelationProvider.getCollectionResourceRelFor(entityInfo.getDomainType()).value();
+		Map<String, Schema> embeddedProperties = entry.getValue().getProperties();
+		if (CollectionUtils.isEmpty(embeddedProperties))
+			return;
 		Schema itemsSchema = null;
 		if (openapi31) {
-			JsonSchema jsonSchema = (JsonSchema) entry.getValue().getProperties().get(entityClassName);
-			if (jsonSchema != null)
+			if (embeddedProperties.get(entityClassName) instanceof JsonSchema jsonSchema)
 				itemsSchema = jsonSchema.getItems();
 		}
 		else {
-			ArraySchema arraySchema = (ArraySchema) entry.getValue().getProperties().get(entityClassName);
-			if (arraySchema != null)
+			if (embeddedProperties.get(entityClassName) instanceof ArraySchema arraySchema)
 				itemsSchema = arraySchema.getItems();
 		}
 		if (itemsSchema != null) {

springdoc-openapi-starter-webmvc-api/src/test/java/test/org/springdoc/api/v30/app272/HelloController.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.v30.app272;
+
+import org.springframework.http.HttpHeaders;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestHeader;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+/**
+ * A controller that asks for every request header at once.
+ *
+ * @author bnasslahsen
+ */
+@RestController
+public class HelloController {
+
+	@GetMapping("/hello")
+	public String hello(@RequestHeader HttpHeaders headers, @RequestParam String name) {
+		return name;
+	}
+}

springdoc-openapi-starter-webmvc-api/src/test/java/test/org/springdoc/api/v30/app272/SpringDocApp272Test.java

@@ -0,0 +1,33 @@
+/*
+ * 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.v30.app272;
+
+import test.org.springdoc.api.v30.AbstractSpringDocV30Test;
+
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+
+/**
+ * An injected HttpHeaders is a request wrapper, not a schema.
+ *
+ * @author bnasslahsen
+ */
+public class SpringDocApp272Test extends AbstractSpringDocV30Test {
+
+	@SpringBootApplication
+	static class SpringDocTestApp {
+	}
+}