strict 模式与 webpack

两个会影响启动行为的设置：一个用于 CI，另一个关于一个架构层面的限制。

strict: true

给 forRoot() 传入 { strict: true }，这样当任何带 @WithDocs() 的控制器没有 companion 文件时，应用会在启动时直接抛出异常。推荐在 CI 中使用：与其得到一份静默不完整的 OpenAPI 文档，不如尽早失败。

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

webpack: true

DocfyModule 的运行时发现机制在这里不生效

如果你的 nest-cli.json 在 compilerOptions 下设置了 "webpack": true，DocfyModule 的 运行时 管线（@WithDocs() + require.cache 发现机制）就不会生效，而且没有任何配置能让它生效。这是架构层面的限制，有两个原因：

第一，webpack 会把每个模块内联进一个单独的 bundle 文件，从不会像每个原始源文件对应一条记录那样填充 Node 的 require.cache，而发现机制正是依赖这一点。你会看到每个带 @WithDocs() 的控制器都报 Could not locate source file for X。

第二，即便绕开了上面这个查找问题，还有第二道无法回避的障碍：从 bundle 外部通过 require() 加载的 docs 文件，会创建一个和运行中的应用实际使用的类在结构上完全不同的类对象。装饰这个孤立的副本，对 SwaggerModule.createDocument() 真正输出的文档没有任何影响，而且这一切都是静默发生的，不会报任何错误。

按优先级排列，仍然有两种方式可以拿到完整文档：

  • CLI 插件（推荐）：使用和 @nestjs/swagger 自身 CLI 插件相同的机制，在每次构建时自动地从根本上解决问题。见 CLI 插件。
  • Use patch-spec：一种手动的、由 CI 驱动的方式，对已经构建好的 OpenAPI 文档做静态打补丁，完全不依赖 require.cache。见 CLI：patch-spec 和 patch-spec：手动替代方案。