Соглашение об именах файлов

Обнаружение происходит само. DocfyModule находит исходный файл каждого контроллера через кеш модулей Node.

Соглашение

Обнаружение происходит само. DocfyModule находит исходный файл каждого контроллера через кеш модулей Node и вычисляет путь к companion-файлу. Это работает одинаково и под ts-node (разработка), и на скомпилированном dist/ (продакшен).

Файл контроллераCompanion-файл
users.controller.tsusers.controller.docs.ts
users.controller.jsusers.controller.docs.js

Реэкспорт через barrel-файлы

Реэкспорт через barrel-файлы

Если контроллер вдобавок экспортируется из barrel-файла index.ts, убедитесь, что класс экспортируется напрямую из своего модуля. nestjs-docfy отдаёт предпочтение .controller.ts, а не barrel-файлам.

Режим сборки webpack: true

Если в nest-cli.json внутри compilerOptions стоит "webpack": true (документированное значение по умолчанию для монорепозиториев с несколькими приложениями), то рантайм-конвейер DocfyModule (обнаружение через @WithDocs() и require.cache, описанное выше) работать не будет, и никакой настройкой это не лечится. Причина архитектурная:

  • Webpack вшивает все модули в один файл сборки и не заполняет require.cache в Node по записи на каждый исходный файл, а механизм обнаружения опирается именно на это. Для каждого контроллера с @WithDocs() вы увидите Could not locate source file for X.
  • Даже если обойти этот поиск (скажем, вытащить исходный путь из source map сборки и вообще не трогать require.cache), впереди вторая стена. Файл документации, подключённый снаружи бандла, создаёт объект класса, структурно отличный от того, которым пользуется запущенное приложение. Декораторы, навешенные на эту свежую копию, никак не влияют на документ, который в итоге отдаёт SwaggerModule.createDocument(). Происходит это молча, без единой ошибки.
  • Единственный обход состоял бы в том, чтобы сам файл контроллера импортировал свой companion .docs.ts и webpack собрал их вместе. Но тогда рушится вся идея соглашения: нулевая связанность контроллера и документации.

Как всё-таки получить полную документацию

Плагин CLI (рекомендуется): пропишите nestjs-docfy в compilerOptions.plugins файла nest-cli.json и вызовите applyDocfyMetadata() сразу после SwaggerModule.createDocument(). Это чинит проблему в корне, автоматически, на каждой сборке. Подробности в разделе Плагин CLI.

Use patch-spec подойдёт как ручная альтернатива из CI, если добавлять плагин компилятора не хочется. Подробности в разделе patch-spec: ручная альтернатива. Либо откажитесь от сборки через webpack: уберите "webpack": true из nest-cli.json или поставьте false. При обычной компиляции через tsc каждый исходный файл превращается в собственный .js, поэтому в require.cache естественным образом появляется по записи на файл, и обнаружение DocfyModule в рантайме работает без правок.