strict mode & webpack

Zwei Einstellungen, die das Verhalten beim Start formen: eine für CI, die andere zu einer architektonischen Einschränkung.

strict: true

Übergib { strict: true } an forRoot(), damit die App beim Start einen Fehler wirft, wenn ein Controller mit @WithDocs() keine Companion-Datei hat. Empfohlen für CI, wo ein schnelles Scheitern einem still unvollständigen OpenAPI-Dokument vorzuziehen ist.

ts
DocfyModule.forRoot({ strict: true });

webpack: true

Die Runtime-Discovery von DocfyModule funktioniert hier nicht

Wenn deine nest-cli.json unter compilerOptions "webpack": true gesetzt hat, funktioniert die Runtime-Pipeline von DocfyModule (die oben beschriebene @WithDocs()- + require.cache-Erkennung) nicht, und es gibt keine Konfiguration, die das ändert. Das ist architektonisch bedingt und hat zwei Ursachen:

Erstens bündelt Webpack jedes Modul in eine einzige Bundle-Datei und befüllt Nodes require.cache nie mit einem Eintrag pro ursprünglicher Quelldatei, worauf der Erkennungsmechanismus angewiesen ist. Du siehst Could not locate source file for X für jeden Controller mit @WithDocs().

Zweitens gibt es, selbst wenn man diesen Lookup umgeht, eine zweite, unumgehbare Mauer: Eine per require() von außerhalb des Bundles geladene Docs-Datei erzeugt ein Klassenobjekt, das strukturell anders ist als das, das die laufende Anwendung intern tatsächlich verwendet. Diese isolierte Kopie zu dekorieren hat keinerlei Effekt auf das Dokument, das SwaggerModule.createDocument() tatsächlich ausliefert, und das passiert lautlos, ohne Fehler.

Zwei Wege zu vollständigen Docs trotzdem, in Reihenfolge der Empfehlung:

  • Das CLI-Plugin (empfohlen): behebt es an der Wurzel, automatisch, bei jedem Build, mit demselben Mechanismus, den auch das eigene CLI-Plugin von @nestjs/swagger nutzt. Siehe Das CLI-Plugin.
  • Use patch-spec: ein manueller, CI-gesteuerter statischer Patch eines bereits gebauten OpenAPI-Dokuments, ohne Abhängigkeit von require.cache. Siehe CLI: patch-spec und patch-spec: manuelle Alternative.