Allow group description metadata to be generated by the configuration properties annotation processor

[philwebb]

Currently we never set a description for item groups, however, our documentation does say that one can be provided in the JSON. It would be nice if we could find a way to support this from the annotation processor.

[mhalbritter]

We have 5 sources of groups from the annotation processor:

1. for @ConfigurationProperties classes
2. for classes where the referencing property is annotated with @NestedConfigurationProperty
3. for nested inner classes in @ConfigurationProperties (even without @NestedConfigurationProperty)
4. for @ConfigurationProperties annotated @Bean methods
5. for actuator endpoints

If we'd add groupDescription attributes to @ConfigurationProperties and @NestedConfigurationProperty, we'd cover cases 1, 2, and 4.

Case 5 doesn't need a custom description, we can hardcode it to "Configuration properties for the '$id' endpoint."

Case 3. is trickier. We could workaround by this: if you want to have a group description, annotate the property with @NestedConfigurationProperty and set groupDescription, even if @NestedConfigurationProperty isn't strictly needed here.

WDYT @philwebb ? I have some changes here, though without tests.

A configuration class would look like this:

@ConfigurationProperties(prefix = "group1", groupDescription = "The group one.")
public class MyConfigProps {
    private String prop1;
    private String prop2;
    @NestedConfigurationProperty(groupDescription = "The nested config props.")
    private final MyNestedConfigProps nestedConfigProps = new MyNestedConfigProps();
    @NestedConfigurationProperty(groupDescription = "The inner config props.")
    private final MyInnerConfigProps myInnerConfigProps = new MyInnerConfigProps();

    // Getter and Setter

    public static class MyInnerConfigProps {
        private String prop5;
        private String prop6;

        // Getter and Setter
    }
}

or like this:

@Configuration(proxyBeanMethods = false)
public class MyConfig {
    @Bean
    @ConfigurationProperties(prefix = "bean", groupDescription = "The bean group.")
    public BeanConfigProps beanConfigProps() {
        return new BeanConfigProps();
    }
}

[philwebb]

I threw added this issue in a bit of a hurry, and I can't exactly remember what I was trying to do at the time. I think I was hoping we could use the field javadoc in a similar way to existing resolveItemMetadataProperty method. Something like:

@ConfigurationProperties(prefix = "group1")
public class MyConfigProps {

    private String prop1;

    private String prop2;

    /** The nested config props. */
    @NestedConfigurationProperty
    private final MyNestedConfigProps nestedConfigProps = new MyNestedConfigProps();

    /** The inner config props. */
    @NestedConfigurationProperty
    private final MyInnerConfigProps myInnerConfigProps = new MyInnerConfigProps();

    // Getter and Setter

    public static class MyInnerConfigProps {
        private String prop5;
        private String prop6;

        // Getter and Setter
    }
}

I think I'd rather not add any annotation attributes if we can help it since we've avoided those so far and nobody except me has asked for the change.

[tinpa-de]

Also discussed in #11616