Режим strict и webpack
Две настройки, от которых зависит поведение при старте: одна нужна для CI, вторая упирается в архитектурное ограничение.
strict: true
Передайте { strict: true } в forRoot(), чтобы приложение падало на старте, когда у контроллера с @WithDocs() нет companion-файла. Для CI это удобнее: лучше упасть сразу, чем молча получить неполный документ OpenAPI.
DocfyModule.forRoot({ strict: true });webpack: true
Если в nest-cli.json внутри compilerOptions стоит "webpack": true, то рантайм-конвейер DocfyModule (обнаружение через @WithDocs() и require.cache) работать не будет, и настройкой это не лечится. Причина архитектурная, и причин на самом деле две:
Первая: webpack складывает все модули в один файл сборки и не заполняет require.cache в Node по записи на каждый исходный файл, а механизм обнаружения опирается именно на это. Для каждого контроллера с @WithDocs() вы увидите Could not locate source file for X.
Вторая: даже обойдя этот поиск, вы упрётесь в следующий барьер. Файл документации, загруженный через require() снаружи бандла, создаёт объект класса, структурно отличный от того, которым внутри пользуется запущенное приложение. Декораторы на этой изолированной копии никак не влияют на документ, который отдаёт SwaggerModule.createDocument(), и происходит это молча, без ошибок.
Получить полную документацию всё же можно двумя способами, в порядке предпочтения:
- Плагин CLI (рекомендуется): чинит проблему в корне, автоматически, на каждой сборке, тем же механизмом, что и собственный плагин CLI из
@nestjs/swagger. Подробности в разделе Плагин CLI. - Use
patch-spec: ручная статическая правка уже собранного документа OpenAPI из CI, без всякой зависимости отrequire.cache. Подробности в разделах CLI: patch-spec и patch-spec: ручная альтернатива.
К "builder": "swc" всё это отношения не имеет. SWC по-прежнему компилирует по файлу на модуль, поэтому require.cache заполняется так же, как при tsc, и обнаружение DocfyModule в рантайме там работает как обычно. Единственная особенность SWC с этим ограничением не связана: чтобы зарегистрировать плагин CLI под SWC, нужен "typeCheck": true, о чём написано в разделе о сборщике SWC в руководстве по плагину.