10. "Мухи" должны быть отделены от "котлет".
Конфигурация генерирования документации Springdoc (Swagger) на API приложения не должна находиться в классе с маршрутизацией web-запросов к API.
Почему? Приведу 2 картинки, вместо 1000 слов.
Некрасиво:
Здесь конфигурация для генерирования документации находится в классе с полезным кодом. Это не очень страшный пример - всего 4 лишних строчки над методом и 1 - над классом. Но это лишь учебный пример. Реальный код может содержить и по 10 строк с конфигурацией для Springdoc (Swagger) над каждым (!) методом. Читать такие "простыни" и искать среди них конфигурацию маршрутов для web API - занятие не для слабонервных. Всё, что осложняет работу программиста, мы осуждаем и отвергаем.
Красиво:
Здесь конфигурация для генерирования документации вынесена из Controller-класса в Api-интерфейс. Видим чистый и красивый код. Хотим работать с маршрутизацией - открываем класс XyzController. Хотим видеть конфигурацию генерирования документации для него - открываем интерфейс XyzApi. Больше наши глаза не болят, а волосы становятся ощутимо шелковистее.
Продолжение следует...