Есть ли хороший способ документировать поля Spring @Value?

Question

В процессе написания приложений для Spring Boot наша команда добавляет множество @Value аннотаций, чтобы сделать их настраиваемыми.В какой-то момент мы начинаем терять, что именно мы добавили и что можно настроить.Мы получаем много вопросов от команд QA и DevOps о том, что именно можно настроить, а что нет.

В настоящее время мы просто выполняем анализ кода и применяем некоторые грубые регулярные выражения, чтобы попытаться разобратьиз значимых частей.Но это не распространяется на 100% случаев, и мы неизбежно копаемся в коде, чтобы выяснить, какие поля можно настроить.

Я знаю, что мы могли бы использовать JavaDoc для некоторого достижения нашей цели, но документациябыть похороненным с другим JavaDoc (методами, полями, классами и т. д.), и разработчики по-прежнему не забывают добавлять JavaDoc в каждое поле.

Кто-нибудь нашел более автоматизированный способ документирования своих полей @Value?Я думаю о чем-то похожем на Swagger, но специально для Spring и различных способов, которыми он может настроить внешнюю конфигурацию.

Answer 1

Javadoc - это действительно способ документировать для разработчиков, а не для QA или операторов.Ваш вопрос действительно интересен, но ответить на него канонически сложно, потому что @Value это детали реализации компонентов.Чванство, что вы цитируете документы REST контрактов , это важное отличие.

Вот несколько идей:

• Написание теста BDD для них, который также можно использовать в качестве документации, на самом деле не имеет смысла функционально, но технически это имеет смысл.Действительно, вы можете написать интеграционный тест BDD (с Cucumber или любой другой библиотекой), где вы документируете и проверяете наличие каждого ожидаемого свойства.

• Не идеальное решение, но вы можете, по крайней мере, получить открытые свойства и немного больше с этими приводами Spring Boot :

configprops: отображает объединенный список всех @ ConfigurationProperties.

env: предоставляет свойства из среды Spring's ConfigurableEnvironment.

• Всякий раз, когда вы можете, предпочитайте @ConfigurationProperties внедрение для группирования свойств, которые работают вместе, а не @Value.Изоляция их в @ConfigurationProperties классах и добавление для них javadoc - это совсем не плохо для документирования их присутствия и использования.

• в соответствии с рекомендациями caco3 вы также можете сгенерировать свои собственные метаданные с помощью процессора аннотаций :

Вы можете легко создать свой собственный файл метаданных конфигурации из элементов, помеченных @ConfigurationProperties ...

Процессор выбирает как классы, так и методы, помеченные @ ConfigurationProperties . Javadoc для значений полей в пределах классов конфигурации используется для заполнения атрибута описания .

Он объединяется с предыдущим пунктом: предпочтение @ConfigurationProperties всякий раз, когда оновозможно.