You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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
Copy file name to clipboardExpand all lines: spring-boot-project/spring-boot-docs/src/docs/antora/modules/specification/pages/configuration-metadata/annotation-processor.adoc
+25-4Lines changed: 25 additions & 4 deletions
Original file line number
Diff line number
Diff line change
@@ -84,9 +84,9 @@ With Gradle, declare the dependencies in the `annotationProcessor` configuration
The processor picks up both classes and methods that are annotated with javadoc:org.springframework.boot.context.properties.ConfigurationProperties[format=annotation].
87
+
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]
88
88
89
-
NOTE: Custom annotations that are meta-annotated with javadoc:org.springframework.boot.context.properties.ConfigurationProperties[format=annotation] are not supported.
89
+
NOTE: Custom annotations that are meta-annotated with either of those annotations are not supported.
90
90
91
91
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].
92
92
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.
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.
101
101
The Javadoc on fields is used to populate the `description` attribute.
102
102
For instance, the description of `my.server.ip` is "IP address to listen to.".
103
+
103
104
The `description` attribute can only be populated when the type is available as source code that is being compiled.
104
105
It will not be populated when the type is only available as a compiled class from a dependency.
105
-
For such cases, xref:configuration-metadata/annotation-processor.adoc#appendix.configuration-metadata.annotation-processor.adding-additional-metadata[manual metadata] should be provided.
106
+
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].
106
107
107
108
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.
108
109
@@ -156,17 +157,37 @@ TIP: This has no effect on collections and maps, as those types are automaticall
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.
164
+
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`.
165
+
166
+
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]:
167
+
168
+
include-code::Host[]
169
+
170
+
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.
171
+
172
+
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.
173
+
174
+
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.
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.
163
182
You may also need to tune some attributes of an existing key or to ignore the key altogether.
164
183
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.
165
184
185
+
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`.
186
+
166
187
If you refer to a property that has been detected automatically, the description, default value, and deprecation information are overridden, if specified.
167
188
If the manual property declaration is not identified in the current module, it is added as a new property.
168
189
169
-
The format of the `additional-spring-configuration-metadata.json` file is exactly the same as the regular `spring-configuration-metadata.json`.
190
+
The format of the additionalmetadata file is exactly the same as the regular `spring-configuration-metadata.json`.
170
191
The items contained in the "`ignored.properties`" section are removed from the "`properties`" section of the generated `spring-configuration-metadata.json` file.
Copy file name to clipboardExpand all lines: spring-boot-project/spring-boot-docs/src/docs/antora/modules/specification/pages/configuration-metadata/index.adoc
+1-1Lines changed: 1 addition & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -6,4 +6,4 @@ Spring Boot jars include metadata files that provide details of all supported co
6
6
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.
7
7
8
8
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].
9
-
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.
9
+
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].
Copy file name to clipboardExpand all lines: spring-boot-project/spring-boot-docs/src/docs/antora/modules/specification/pages/configuration-metadata/manual-hints.adoc
+2Lines changed: 2 additions & 0 deletions
Original file line number
Diff line number
Diff line change
@@ -42,6 +42,8 @@ In order to offer additional content assistance for the keys, you could add the
42
42
]}
43
43
----
44
44
45
+
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.
46
+
45
47
TIP: We recommend that you use an javadoc:java.lang.Enum[] for those two values instead.
46
48
If your IDE supports it, this is by far the most effective approach to auto-completion.
Copy file name to clipboardExpand all lines: spring-boot-project/spring-boot-tools/spring-boot-configuration-processor/src/main/java/org/springframework/boot/configurationprocessor/ConfigurationMetadataAnnotationProcessor.java
0 commit comments