Add metadata support for types in arbitrary modules

Previously, if a ConfigurationProperties had a nested type or was
extending from a type located outside the compilation unit, no
metadata discovered on the source code was available (documentation and
explicit default value, if any). This typically happens when such a type
resides in another module.

This commit introduces `@ConfigurationPropertiesSource` as a way to
annotate such type and have metadata generated for them in their own
module.

Type-metadata is generated as one file per type and is reused
transparently whenever that type is used. As for module metadata, an
additional file can be crafted manually and will be merged when the
metadata for the type is generated.

The following is an example structure with two types where one has
an additional metadata:

META-iNF/
  spring/
    configuration-properties/
      additional/
        com.example.SourceOne.json
      com.example.SourceOne.json
      com.example.SourceTwo.json

Those files are used only by the annotation processor and are not meant
to be public API.

See gh-18366

Author: snicoll

spring-boot-project/spring-boot-docs/src/docs/antora/modules/specification/pages/configuration-metadata/annotation-processor.adoc

@@ -84,9 +84,9 @@ With Gradle, declare the dependencies in the `annotationProcessor` configuration
 [[appendix.configuration-metadata.annotation-processor.automatic-metadata-generation]]
 == Automatic Metadata Generation
 
-The processor picks up both classes and methods that are annotated with javadoc:org.springframework.boot.context.properties.ConfigurationProperties[format=annotation].
+The processor picks up both classes and methods that are annotated with javadoc:org.springframework.boot.context.properties.ConfigurationProperties[format=annotation]. It also picks classes that are annotated with javadoc:org.springframework.boot.context.properties.ConfigurationPropertiesSource[format=annotation]
 
-NOTE: Custom annotations that are meta-annotated with javadoc:org.springframework.boot.context.properties.ConfigurationProperties[format=annotation] are not supported.
+NOTE: Custom annotations that are meta-annotated with either of those annotations are not supported.
 
 If the class has a single parameterized constructor, one property is created per constructor parameter, unless the constructor is annotated with javadoc:org.springframework.beans.factory.annotation.Autowired[format=annotation].
 If the class has a constructor explicitly annotated with javadoc:org.springframework.boot.context.properties.bind.ConstructorBinding[format=annotation], one property is created per constructor parameter for that constructor.
@@ -100,9 +100,10 @@ include-code::MyServerProperties[]
 This exposes three properties where `my.server.name` has no default and `my.server.ip` and `my.server.port` defaults to `"127.0.0.1"` and `9797` respectively.
 The Javadoc on fields is used to populate the `description` attribute.
 For instance, the description of `my.server.ip` is "IP address to listen to.".
+
 The `description` attribute can only be populated when the type is available as source code that is being compiled.
 It will not be populated when the type is only available as a compiled class from a dependency.
-For such cases, xref:configuration-metadata/annotation-processor.adoc#appendix.configuration-metadata.annotation-processor.adding-additional-metadata[manual metadata] should be provided.
+For such cases, you can xref:configuration-metadata/annotation-processor.adoc#appendix.configuration-metadata.annotation-processor.automatic-metadata-generation.source[source the metadata] or xref:configuration-metadata/annotation-processor.adoc#appendix.configuration-metadata.annotation-processor.adding-additional-metadata[provide manual entries].
 
 NOTE: You should only use plain text with javadoc:org.springframework.boot.context.properties.ConfigurationProperties[format=annotation] field Javadoc, since they are not processed before being added to the JSON.
 
@@ -156,17 +157,37 @@ TIP: This has no effect on collections and maps, as those types are automaticall
 
 
 
+[[appendix.configuration-metadata.annotation-processor.automatic-metadata-generation.source]]
+=== Configuration Properties Source
+
+If a type located in another module is used in a javadoc:org.springframework.boot.context.properties.ConfigurationProperties[format=annotation]-annotated type, some metadata elements cannot be discovered automatically.
+Reusing the example above, if `Host` is located in another module, full metadata is not available as the annotation processor does not have access to the source of `Host`.
+
+To handle this use case, add the annotation processor in the module that contains the `Host` type and annotate it with javadoc:org.springframework.boot.context.properties.ConfigurationPropertiesSource[format=annotation]:
+
+include-code::Host[]
+
+This generates the metadata for `Host` in `META-INF/spring/configuration-metadata/com.example.Host.json` and is reused automatically by the annotation processor when it handles such type.
+
+You can also annotate a parent class located in another module that a javadoc:org.springframework.boot.context.properties.ConfigurationProperties[format=annotation]-annotated type extends from.
+
+TIP: If you need to reuse metadata for a type that you do not control, create a file named with the pattern above and it will be used as long as it is available on the classpath.
+
+
+
 [[appendix.configuration-metadata.annotation-processor.adding-additional-metadata]]
 == Adding Additional Metadata
 
 Spring Boot's configuration file handling is quite flexible, and it is often the case that properties may exist that are not bound to a javadoc:org.springframework.boot.context.properties.ConfigurationProperties[format=annotation] bean.
 You may also need to tune some attributes of an existing key or to ignore the key altogether.
 To support such cases and let you provide custom "hints", the annotation processor automatically merges items from `META-INF/additional-spring-configuration-metadata.json` into the main metadata file.
 
+When generating source metadata for a type, you can also craft custom metadata for that type, for example `com.example.SomeType`, in `META-INF/spring/configuration/metadata/com.example.SomeType.json`.
+
 If you refer to a property that has been detected automatically, the description, default value, and deprecation information are overridden, if specified.
 If the manual property declaration is not identified in the current module, it is added as a new property.
 
-The format of the `additional-spring-configuration-metadata.json` file is exactly the same as the regular `spring-configuration-metadata.json`.
+The format of the additional metadata file is exactly the same as the regular `spring-configuration-metadata.json`.
 The items contained in the "`ignored.properties`" section are removed from the "`properties`" section of the generated  `spring-configuration-metadata.json` file.
 
 The additional properties file is optional.

spring-boot-project/spring-boot-docs/src/docs/antora/modules/specification/pages/configuration-metadata/index.adoc

@@ -6,4 +6,4 @@ Spring Boot jars include metadata files that provide details of all supported co
 The files are designed to let IDE developers offer contextual help and "`code completion`" as users are working with `application.properties` or `application.yaml` files.
 
 The majority of the metadata file is generated automatically at compile time by processing all items annotated with javadoc:org.springframework.boot.context.properties.ConfigurationProperties[format=annotation].
-However, it is possible to xref:configuration-metadata/annotation-processor.adoc#appendix.configuration-metadata.annotation-processor.adding-additional-metadata[write part of the metadata manually] for corner cases or more advanced use cases.
+For corner cases or more advanced use cases, it is possible to xref:configuration-metadata/annotation-processor.adoc#appendix.configuration-metadata.annotation-processor.automatic-metadata-generation.source[source the metadata of external types ] or xref:configuration-metadata/annotation-processor.adoc#appendix.configuration-metadata.annotation-processor.adding-additional-metadata[write part of the metadata manually].

spring-boot-project/spring-boot-docs/src/docs/antora/modules/specification/pages/configuration-metadata/manual-hints.adoc

@@ -42,6 +42,8 @@ In order to offer additional content assistance for the keys, you could add the
 ]}
 ----
 
+NOTE: Hints can also be added for xref:configuration-metadata/annotation-processor.adoc#appendix.configuration-metadata.annotation-processor.automatic-metadata-generation.source[external types] and are applied whenever that type is used.
+
 TIP: We recommend that you use an javadoc:java.lang.Enum[] for those two values instead.
 If your IDE supports it, this is by far the most effective approach to auto-completion.
 

spring-boot-project/spring-boot-docs/src/main/java/org/springframework/boot/docs/appendix/configurationmetadata/annotationprocessor/automaticmetadatageneration/source/Host.java

@@ -0,0 +1,52 @@
+/*
+ * Copyright 2012-2025 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.springframework.boot.docs.appendix.configurationmetadata.annotationprocessor.automaticmetadatageneration.source;
+
+import org.springframework.boot.context.properties.ConfigurationPropertiesSource;
+
+@ConfigurationPropertiesSource
+public class Host {
+
+	/**
+	 * IP address to listen to.
+	 */
+	private String ip = "127.0.0.1";
+
+	/**
+	 * Port to listener to.
+	 */
+	private int port = 9797;
+
+	// @fold:on // getters/setters ...
+	public String getIp() {
+		return this.ip;
+	}
+
+	public void setIp(String ip) {
+		this.ip = ip;
+	}
+
+	public int getPort() {
+		return this.port;
+	}
+
+	public void setPort(int port) {
+		this.port = port;
+	}
+	// @fold:off
+
+}

spring-boot-project/spring-boot-docs/src/main/kotlin/org/springframework/boot/docs/configurationmetadata/annotationprocessor/automaticmetadatageneration/source/Host.kt

@@ -0,0 +1,19 @@
+package org.springframework.boot.docs.configurationmetadata.annotationprocessor.automaticmetadatageneration.source
+
+import org.springframework.boot.context.properties.ConfigurationPropertiesScan
+
+@ConfigurationPropertiesScan
+class Host {
+
+	/**
+	 * IP address to listen to.
+	 */
+	var ip: String = "127.0.0.1"
+
+	/**
+	 * Port to listener to.
+	 */
+	var port = 9797
+
+
+}

spring-boot-project/spring-boot-tools/spring-boot-configuration-processor/src/main/java/org/springframework/boot/configurationprocessor/ConfigurationMetadataAnnotationProcessor.java

@@ -16,7 +16,6 @@
 
 package org.springframework.boot.configurationprocessor;
 
-import java.io.FileNotFoundException;
 import java.io.PrintWriter;
 import java.io.StringWriter;
 import java.time.Duration;
@@ -28,6 +27,7 @@
 import java.util.Map;
 import java.util.Objects;
 import java.util.Set;
+import java.util.function.Supplier;
 
 import javax.annotation.processing.AbstractProcessor;
 import javax.annotation.processing.ProcessingEnvironment;
@@ -48,6 +48,7 @@
 import org.springframework.boot.configurationprocessor.metadata.ConfigurationMetadata;
 import org.springframework.boot.configurationprocessor.metadata.InvalidConfigurationMetadataException;
 import org.springframework.boot.configurationprocessor.metadata.ItemDeprecation;
+import org.springframework.boot.configurationprocessor.metadata.ItemHint;
 import org.springframework.boot.configurationprocessor.metadata.ItemIgnore;
 import org.springframework.boot.configurationprocessor.metadata.ItemMetadata;
 
@@ -64,6 +65,7 @@
  * @since 1.2.0
  */
 @SupportedAnnotationTypes({ ConfigurationMetadataAnnotationProcessor.CONFIGURATION_PROPERTIES_ANNOTATION,
+		ConfigurationMetadataAnnotationProcessor.CONFIGURATION_PROPERTIES_SOURCE_ANNOTATION,
 		ConfigurationMetadataAnnotationProcessor.AUTO_CONFIGURATION_ANNOTATION,
 		ConfigurationMetadataAnnotationProcessor.CONFIGURATION_ANNOTATION,
 		ConfigurationMetadataAnnotationProcessor.CONTROLLER_ENDPOINT_ANNOTATION,
@@ -78,6 +80,8 @@ public class ConfigurationMetadataAnnotationProcessor extends AbstractProcessor
 
 	static final String CONFIGURATION_PROPERTIES_ANNOTATION = "org.springframework.boot.context.properties.ConfigurationProperties";
 
+	static final String CONFIGURATION_PROPERTIES_SOURCE_ANNOTATION = "org.springframework.boot.context.properties.ConfigurationPropertiesSource";
+
 	static final String NESTED_CONFIGURATION_PROPERTY_ANNOTATION = "org.springframework.boot.context.properties.NestedConfigurationProperty";
 
 	static final String DEPRECATED_CONFIGURATION_PROPERTY_ANNOTATION = "org.springframework.boot.context.properties.DeprecatedConfigurationProperty";
@@ -116,6 +120,8 @@ public class ConfigurationMetadataAnnotationProcessor extends AbstractProcessor
 
 	private MetadataStore metadataStore;
 
+	private MetadataCollectors metadataCollectors;
+
 	private MetadataCollector metadataCollector;
 
 	private MetadataGenerationEnvironment metadataEnv;
@@ -124,6 +130,10 @@ protected String configurationPropertiesAnnotation() {
 		return CONFIGURATION_PROPERTIES_ANNOTATION;
 	}
 
+	protected String configurationPropertiesSourceAnnotation() {
+		return CONFIGURATION_PROPERTIES_SOURCE_ANNOTATION;
+	}
+
 	protected String nestedConfigurationPropertyAnnotation() {
 		return NESTED_CONFIGURATION_PROPERTY_ANNOTATION;
 	}
@@ -178,23 +188,35 @@ public Set<String> getSupportedOptions() {
 	@Override
 	public synchronized void init(ProcessingEnvironment env) {
 		super.init(env);
-		this.metadataStore = new MetadataStore(env);
-		this.metadataCollector = new MetadataCollector(env, this.metadataStore.readMetadata());
+		TypeUtils typeUtils = new TypeUtils(env);
+		this.metadataStore = new MetadataStore(env, typeUtils);
+		this.metadataCollectors = new MetadataCollectors(env, typeUtils);
+		this.metadataCollector = this.metadataCollectors.getModuleMetadataCollector();
 		this.metadataEnv = new MetadataGenerationEnvironment(env, configurationPropertiesAnnotation(),
-				nestedConfigurationPropertyAnnotation(), deprecatedConfigurationPropertyAnnotation(),
-				constructorBindingAnnotation(), autowiredAnnotation(), defaultValueAnnotation(), endpointAnnotations(),
-				readOperationAnnotation(), optionalParameterAnnotation(), nameAnnotation());
+				configurationPropertiesSourceAnnotation(), nestedConfigurationPropertyAnnotation(),
+				deprecatedConfigurationPropertyAnnotation(), constructorBindingAnnotation(), autowiredAnnotation(),
+				defaultValueAnnotation(), endpointAnnotations(), readOperationAnnotation(),
+				optionalParameterAnnotation(), nameAnnotation());
 	}
 
 	@Override
 	public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
-		this.metadataCollector.processing(roundEnv);
+		this.metadataCollectors.processing(roundEnv);
 		TypeElement annotationType = this.metadataEnv.getConfigurationPropertiesAnnotationElement();
 		if (annotationType != null) { // Is @ConfigurationProperties available
 			for (Element element : roundEnv.getElementsAnnotatedWith(annotationType)) {
 				processElement(element);
 			}
 		}
+		TypeElement sourceAnnotationType = this.metadataEnv.getConfigurationPropertiesSourceAnnotationElement();
+		if (sourceAnnotationType != null) { // Is @ConfigurationPropertiesSource available
+			for (Element element : roundEnv.getElementsAnnotatedWith(sourceAnnotationType)) {
+				if (element instanceof TypeElement typeElement) {
+					MetadataCollector metadataCollector = this.metadataCollectors.getMetadataCollector(typeElement);
+					processSourceElement(metadataCollector, "", typeElement);
+				}
+			}
+		}
 		Set<TypeElement> endpointTypes = this.metadataEnv.getEndpointAnnotationElements();
 		if (!endpointTypes.isEmpty()) { // Are endpoint annotations available
 			for (TypeElement endpointType : endpointTypes) {
@@ -203,6 +225,7 @@ public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment
 		}
 		if (roundEnv.processingOver()) {
 			try {
+				writeSourceMetadata();
 				writeMetadata();
 			}
 			catch (Exception ex) {
@@ -276,6 +299,10 @@ private void processTypeElement(String prefix, TypeElement element, ExecutableEl
 			seen.push(element);
 			new PropertyDescriptorResolver(this.metadataEnv).resolve(element, source).forEach((descriptor) -> {
 				this.metadataCollector.add(descriptor.resolveItemMetadata(prefix, this.metadataEnv));
+				ItemHint itemHint = descriptor.resolveItemHint(prefix, this.metadataEnv);
+				if (itemHint != null) {
+					this.metadataCollector.add(itemHint);
+				}
 				if (descriptor.isNested(this.metadataEnv)) {
 					TypeElement nestedTypeElement = (TypeElement) this.metadataEnv.getTypeUtils()
 						.asElement(descriptor.getType());
@@ -287,6 +314,18 @@ private void processTypeElement(String prefix, TypeElement element, ExecutableEl
 		}
 	}
 
+	private void processSourceElement(MetadataCollector metadataCollector, String prefix, TypeElement element) {
+		new PropertyDescriptorResolver(this.metadataEnv).resolve(element, null).forEach((descriptor) -> {
+			metadataCollector.add(descriptor.resolveItemMetadata(prefix, this.metadataEnv));
+			if (descriptor.isNested(this.metadataEnv)) {
+				TypeElement nestedTypeElement = (TypeElement) this.metadataEnv.getTypeUtils()
+					.asElement(descriptor.getType());
+				String nestedPrefix = ConfigurationMetadata.nestedPrefix(prefix, descriptor.getName());
+				processSourceElement(metadataCollector, nestedPrefix, nestedTypeElement);
+			}
+		});
+	}
+
 	private void processEndpoint(Element element, List<Element> annotations) {
 		try {
 			String annotationName = this.metadataEnv.getTypeUtils().getQualifiedName(annotations.get(0));
@@ -381,9 +420,20 @@ private String getPrefix(AnnotationMirror annotation) {
 		return this.metadataEnv.getAnnotationElementStringValue(annotation, "value");
 	}
 
+	protected void writeSourceMetadata() throws Exception {
+		for (TypeElement sourceType : this.metadataCollectors.getSourceTypes()) {
+			ConfigurationMetadata metadata = this.metadataCollectors.getMetadataCollector(sourceType).getMetadata();
+			metadata = mergeAdditionalMetadata(metadata, () -> this.metadataStore.readAdditionalMetadata(sourceType));
+			removeIgnored(metadata);
+			if (!metadata.getItems().isEmpty()) {
+				this.metadataStore.writeMetadata(metadata, sourceType);
+			}
+		}
+	}
+
 	protected ConfigurationMetadata writeMetadata() throws Exception {
 		ConfigurationMetadata metadata = this.metadataCollector.getMetadata();
-		metadata = mergeAdditionalMetadata(metadata);
+		metadata = mergeAdditionalMetadata(metadata, () -> this.metadataStore.readAdditionalMetadata());
 		removeIgnored(metadata);
 		if (!metadata.getItems().isEmpty()) {
 			this.metadataStore.writeMetadata(metadata);
@@ -398,14 +448,16 @@ private void removeIgnored(ConfigurationMetadata metadata) {
 		}
 	}
 
-	private ConfigurationMetadata mergeAdditionalMetadata(ConfigurationMetadata metadata) {
+	private ConfigurationMetadata mergeAdditionalMetadata(ConfigurationMetadata metadata,
+			Supplier<ConfigurationMetadata> additionalMetadataSupplier) {
 		try {
-			ConfigurationMetadata merged = new ConfigurationMetadata(metadata);
-			merged.merge(this.metadataStore.readAdditionalMetadata());
-			return merged;
-		}
-		catch (FileNotFoundException ex) {
-			// No additional metadata
+			ConfigurationMetadata additionalMetadata = additionalMetadataSupplier.get();
+			if (additionalMetadata != null) {
+				ConfigurationMetadata merged = new ConfigurationMetadata(metadata);
+				merged.merge(additionalMetadata);
+				return merged;
+			}
+			return metadata;
 		}
 		catch (InvalidConfigurationMetadataException ex) {
 			log(ex.getKind(), ex.getMessage());