Почему документация Swagger не генерируется автоматически? Потому что Swagger UI ничего не генерирует сам — он лишь отрисовывает уже готовый OpenAPI-файл, который создаёт отдельная библиотека: springdoc-openapi или springfox в Java, Swashbuckle в ASP.NET Core, drf-spectacular в Django, FastAPI во Python. Если эта библиотека не подключена к проекту, её middleware не зарегистрировано в конвейере обработки запросов или сканирование контроллеров не находит ни одного аннотированного маршрута, спецификация не собирается и страница Swagger UI остаётся пустой либо отдаёт 404.
Первым делом проверьте сам источник данных, а не интерфейс: откройте в браузере путь /v3/api-docs для springdoc, /swagger/v1/swagger.json для Swashbuckle, /openapi.json для FastAPI. Если по этому адресу возвращается JSON — генерация работает, и проблема в настройках Swagger UI, например в неверном значении url или в блокировке статики. Если возвращается ошибка — ищите причину в генераторе.
Короткий чек-лист для диагностики: зависимость генератора добавлена в сборку и подтянута менеджером пакетов; middleware или эндпоинт спецификации зарегистрирован до маршрутизации приложения; хотя бы один контроллер помечен аннотацией и попадает в область сканирования, заданную в конфигурации; базовый путь не перекрыт префиксом или обратным прокси; для защищённых проектов отключены фильтры безопасности, блокирующие служебные адреса. Отдельный частый нюанс — при сборке в native-образ или при обфускации сканирование аннотаций ломается, и спецификацию приходится описывать вручную.