Enhance the output formats of the configuration processor of Spring Boot

[obfischer]

I am maintaining a large application with hunderts of configuration properties. The ops teams would like to have a overview and documentation of all the properties. Actual all information I need is already in spring-configuration-metadata.json, but I would like to have the documentation in Asciidoc or Markdown. Currently I have prototype for a processing chain from JSON to Asciidoc via a Groovy script executed during the Maven build.

It would be nice to be able also to generate the same content as Asciidoc or Markdown with standard tooling directly from the build of a project.

The straight forward solution is simple to enhance the output of the configuration processor. This is quite simple. Although this could raise the discusion on the correct formatting of the output and clearly there is to standard or common way of formatting. Therefore I see the following options:

• Generate directly Asciidoc and Markdown
• Generate a intermediate format as XML, which could be transformed via XSLT to the desired format
• Do both

I would be happy to contribute this enhancement, if someone would support me with the solution design.

[philwebb]

Having a standard way to do this might be quite nice, although I worry a little that every user will want a slightly different output. Incidentally, we have this code in our own build which we use to generate https://docs.spring.io/spring-boot/docs/current/reference/html/application-properties.html#appendix.application-properties

Flagging for team discussion (probably in the new year now)

[obfischer]

Hi @philwebb, yes, the different desires on the output are an issue. Therefore I suggested XML too as output format. The reason why is, that in a Java based pipeline we have all the tooling to transform XML to any output. If there is a better way or more accepted intermediate format, then this one should be choosen.

[nandorholozsnyak]

Hello @obfischer

In my team we were also having the same problem, we are having a lot of configuration properties and we are just not collecting them in a common place, so I've been working on a tool lately and maybe it can help you as well in the process.

It can generate you Markdown, AsciiDoc, HTML and XML (as you mentioned, basically we did not want to create this output format, but after reading this issue we made it too :))

Right now you can use it with Maven or with JBang. Gradle plugin will be coming soon.

https://github.com/rodnansol/spring-configuration-property-documenter

If you try it out, let me know if you encounter any bugs.

PM: This is not some sort of advertisement about the tool, I hope it can help your team as it does with mine too.

[philwebb]

We discussed this today as a team and don't think that we can create output that will please all people and cover all use-cases without significant effort. We also don't want to ship XML variants of the config data since we feel that having two different file formats might be confusing and it will be more code for us to maintain.

We do think that the current JSON could be improved so that it's more complete. We have issues #33621 and #7562 open to cover this (and we can add more issues if additional changes are needed).

Thanks for the suggestion and thanks as well to @nandorholozsnyak for creating the spring-configuration-property-documenter tool.

[obfischer]

Hi @philwebb, thank you for disussing and considering my issue. 🙇🏻