Konwencja nazewnictwa plików

Wykrywanie jest automatyczne. DocfyModule lokalizuje plik źródłowy każdego kontrolera przez cache modułów Node'a.

Konwencja

Wykrywanie jest automatyczne. DocfyModule lokalizuje plik źródłowy każdego kontrolera przez cache modułów Node'a i rozwiązuje ścieżkę towarzyszącą: działa to identycznie zarówno pod ts-node (development), jak i skompilowanym dist/ (produkcja).

Plik kontroleraPlik towarzyszący
users.controller.tsusers.controller.docs.ts
users.controller.jsusers.controller.docs.js

Reeksporty barrel

Reeksporty barrel

Jeśli Twój kontroler jest też eksportowany z barrela index.ts, upewnij się, że klasa jest eksportowana bezpośrednio z własnego pliku modułu. nestjs-docfy preferuje .controller.ts nad plikami barrel.

tryb builda webpack: true

Jeśli Twój nest-cli.json ma "webpack": true pod compilerOptions (udokumentowany domyślny ustawienie dla monorepo z wieloma aplikacjami), pipeline runtime DocfyModule (opisane wyżej wykrywanie @WithDocs() + require.cache) nie zadziała, i żadna konfiguracja tego nie zmieni. To ograniczenie architektoniczne:

  • Webpack łączy każdy moduł w jeden plik bundla i nigdy nie wypełnia require.cache Node'a jednym wpisem na oryginalny plik źródłowy, na czym opiera się mechanizm wykrywania. Zobaczysz Could not locate source file for X dla każdego kontrolera z @WithDocs().
  • Nawet jeśli to wyszukiwanie zostanie obejście (na przykład przez odzyskanie oryginalnej ścieżki z source mapy bundla, z pominięciem require.cache), jest druga, nieunikniona ściana: plik docs wymagany spoza bundla tworzy obiekt klasy strukturalnie różny od tego, którego wewnętrznie używa działająca aplikacja. Dekorowanie tej świeżej kopii nie ma żadnego wpływu na dokument, który faktycznie zwraca SwaggerModule.createDocument(). Dzieje się to po cichu, bez żadnego błędu.
  • Jedynym sposobem obejścia byłoby, żeby sam plik kontrolera importował swojego towarzysza .docs.ts (zmuszając webpack do połączenia obu razem), co przekreśla cały sens konwencji: zerowe sprzężenie między kontrolerem a dokumentacją.

Jak mimo to mieć pełną dokumentację

Plugin CLI (rekomendowany): zarejestruj nestjs-docfy w compilerOptions.plugins pliku nest-cli.json i wywołaj applyDocfyMetadata() zaraz po SwaggerModule.createDocument(). Naprawia to u źródła, automatycznie, przy każdym buildzie. Zobacz The CLI plugin.

Use patch-spec jako ręczna, sterowana przez CI alternatywa, jeśli wolisz nie dodawać pluginu kompilatora. Zobacz patch-spec: manual alternative. Albo całkowicie wyłącz bundlowanie webpackiem: usuń "webpack": true (albo ustaw na false) w nest-cli.json. Przy domyślnej kompilacji opartej na tsc, każdy plik źródłowy kompiluje się do własnego .js, więc require.cache naturalnie ma jeden wpis na plik, a runtime'owe wykrywanie DocfyModule działa bez modyfikacji.