Какой жизненный цикл для аннотации Java, которая генерирует документацию?

Question

Я бы хотел иметь возможность документировать зависимости моих сервисов непосредственно в моем коде, используя аннотации Java. Эти аннотации могут содержать информацию о целевой системе, о том, является ли соединение входящим / исходящим / двухсторонним, и тип соединения (REST, RabbitMQ ...).

Это может выглядеть так:

@Dependency(target = "Twitter API", type = "Outgoing", medium = "REST") 

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

У меня есть четкое представление о том, как создать собственную аннотацию с необходимыми атрибутами. Тем не менее, я не уверен на , какую часть жизненного цикла компиляции / обработки я должен обрабатывать эти аннотации.

Я понимаю, что процессоры аннотаций генерируют исходные файлы, но в моем случае сгенерированные файлы вообще не требуются ни компилятором, ни самим приложением.

В идеале я хотел бы иметь возможность запускать обработку аннотаций и создание файла DOT с помощью специальной задачи Maven или Gradle.

Это что-то, что легко выполнимо при написании моих собственных аннотаций?

Answer 1

Аннотации обрабатываются непосредственно компилятором Java.

Для Maven можно использовать maven-compiler-plugin. Также возможно выполнить компиляцию в 2 этапа, как объяснено здесь .

Для Gradle можно добавить процессоры в блок dependencies в конфигурации annotationProcessor, как объяснено здесь .

Аннотация Сохранение можно указать как SOURCE, поэтому они не будут сохранены после компиляции.

Answer 2

Если вы хотите создать документацию через maven, вам нужно добавить ниже две зависимости как плагины, а затем выполнить site maven goal.

        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-site-plugin</artifactId>
            <version>3.7.1</version>
        </plugin>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-project-info-reports-plugin</artifactId>
            <version>3.0.0</version>
        </plugin>

Если вы просто хотите документировать конечные точки REST, вы можете использовать swagger. Если ваш проект использует Spring, то интеграция Swagger довольно проста. Вы можете использовать этот учебник.

Если вы хотите сохранить в файле граф зависимостей вашего проекта, вы можете просто выполнить следующую команду maven.

mvn dependency:tree -Doutput=/path/to/file