tryb strict i webpack
Dwa ustawienia kształtujące zachowanie przy starcie: jedno dla CI, drugie dotyczące ograniczenia architektonicznego.
strict: true
Przekaż { strict: true } do forRoot(), aby aplikacja rzucała wyjątek przy starcie, gdy jakikolwiek kontroler z @WithDocs() nie ma pliku towarzyszącego. Rekomendowane dla CI, gdzie szybka awaria jest lepsza niż cicho niekompletny dokument OpenAPI.
DocfyModule.forRoot({ strict: true });webpack: true
Jeśli Twój nest-cli.json ma "webpack": true pod compilerOptions, pipeline runtime DocfyModule (wykrywanie @WithDocs() + require.cache) nie zadziała, i żadna konfiguracja tego nie zmieni. To ograniczenie architektoniczne, z dwiema przyczynami:
Po pierwsze, 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().
Po drugie, nawet obchodząc to wyszukiwanie, jest druga, nieunikniona bariera: plik docs wczytany przez require() spoza bundla tworzy obiekt klasy strukturalnie różny od tego, którego faktycznie używa wewnętrznie działająca aplikacja. Dekorowanie tej odizolowanej kopii nie ma żadnego wpływu na dokument, który faktycznie zwraca SwaggerModule.createDocument(), i dzieje się to po cichu, bez żadnego błędu.
Dwa sposoby na pełną dokumentację mimo to, w kolejności preferencji:
- Plugin CLI (rekomendowany): naprawia to u źródła, automatycznie, przy każdym buildzie, tym samym mechanizmem, którego używa własny plugin CLI
@nestjs/swagger. Zobacz The CLI plugin. - Use
patch-spec: ręczna, sterowana przez CI statyczna łatka już zbudowanego dokumentu OpenAPI, bez zależności odrequire.cache. Zobacz CLI: patch-spec i patch-spec: manual alternative.