Requirement
Recently we had a requirement to have the description for properties of subObjects and to do so we applied @NestedConfigurationProperties over the property of type subobject but after the use of this annotation we lost the javadoc(description) written over property of type subobject in Configuration class.
Current behavior
Currently spring-boot-configuration-processor doesn't provide the Javadoc as description for properties annotated with @NestedConfigurationProperty in generated spring-configuration-metadata.json file, as this property becomes the part of Group instead of Properties in the spring-configuration-metadata.json file .
Findings from analysis on current code of spring-boot-configuration-processor
After having a look into the code, figured out that if element is annotated with @NestedConfigurationPropeties then it is considered as a item of type group and in that case there is no logic written into the code responsible for collecting the description of such properties.
We did some modification in spring-boot-configuration-processor module of spring-boot project and were able to get the description of properties annotated with @NestedConfigurationProperty.
Modification done by us to get the description of properties annotated with @NestedConfigurationProperty
To do so we made changes in PropertyDescriptor (methodName = resolveItemMetadataGroup) class to get the description of nested properties as well and then add this description in ItemMetaData (method name = newGroup) instead of null.
above method is referred by this method
Comment From: wilkinsona
It's hard to be certain as you haven't shown any code, but it sounds like @NestedConfigurationProperty may be behaving as its javadoc describes. Can we please take a step back? We need to fully understand the problem before we can consider making a change. To help with that, can you share a minimal sample that reproduces your problem?
Comment From: mukul20798
Hi @wilkinsona ,
Here is the uploaded sample to reproduce the issue.
In the sample, DatabaseProperties class contains a property named 'server' of type Server class.
Without @NestedConfigurationProperty
There is a description written over property server in DatabaseProperties class and if we don't annotate the server property with @NestedConfigurationProperty annotation then properties section of generated metadata file contains an entry for property server with its description.
With @NestedConfigurationProperty
Now to get the metadata of properties of Server class(subobject), it is recommended to use @NestedConfigurationProperties annotation over server property in DatabaseProperties class. And after applying this annotation we get the metadata for properties of Server class in properties section of generated metadata file.
But now property server becomes the part of group section of metadata file and we lost the description written over server property.
Comment From: wilkinsona
Thanks for the sample. I now understand the problem.
Without @NestedConfigurationProperty, the annotation processor incorrectly treats database.server as a property that can be configured. This is incorrect as setting database.server will not work – database.server.ip and database.server.port must be set instead.
When you add @NestedConfigurationProperty, the annotation processor now knows that database.server itself isn't a property and that the Server class defines a group a properties and that should be processed to determine what those properties are. This processing finds the database.server.ip and database.server.port properties and generates metadata for them.
In short, this is working as designed because database.server is a group of properties rather than a property. Using @NestedConfigurationProperty tells the annotation processor this and results in it correctly generating metadata for the group and its properties.
Comment From: mukul20798
Hi @wilkinsona ,
I think you have misunderstood our intention.
can you please suggest me how to get the description(Javadoc) written over the server property when it is annotated with @NestedConfigurationProperty ?
Comment From: wilkinsona
There is no server property, it's just a group (a container) for the ip and port properties. You'll see the same behavior if you make Server an inner-class of DatabaseProperties and don't use @NestedConfigurationProperty.
Comment From: deepakrghv
Hi @wilkinsona
Still If it is group(a container), should we add its description in the generated metadata file.?
Comment From: wilkinsona
IMO, there's no benefit to providing a description for a group as I don't think consumers of the metadata would use it. For example, I don't think an IDE (the primary consumers of the metadata) would have any use for it.
Comment From: deepakrghv
Actually we have one use case, where also need to show description in the auto-completion shown by intellij if user try to enter group level entity like here as "server"
Comment From: wilkinsona
IntelliJ, and other IDEs that I am aware of, don't show the groups or offer auto-completion for them. Furthermore, I don't think it makes sense for them to do so. The description of an individual property should provide sufficient information for a user to know what it does. They should not have to refer to documentation for the property's group as well.