docfy generate

扫描你的项目，为每个控制器生成预填充好的 *.controller.docs.ts，仅做静态分析，不执行任何项目代码。

用法

bash

npx nestjs-docfy generate [options]

Option	Default	Description
`--root <path>`	`.`	Project root directory
`--tsconfig <path>`	auto-detected	Path to `tsconfig.json`
`--pattern <glob>`	`*/.controller.ts`	Glob pattern to find controllers
`--out <path>`	alongside each controller	Output directory for generated files
`--force`	`false`	Merge new methods into existing docs files (preserves user edits)
`--overwrite`	`false`	Discard existing docs file content and regenerate it from scratch (takes precedence over --force)
`--dry-run`	`false`	Print what would be generated without writing files
`--quiet`	`false`	Suppress all output except errors (CI-friendly)
`--format`	`ts`	Output format: `ts` or `js`
`--watch`	`false`	Re-generate on controller file changes
`--register-plugin`	`false`	If `webpack: true` is set without the CLI plugin, add `nestjs-docfy` to `nest-cli.json`'s `compilerOptions.plugins`. See The CLI plugin.
`--link-controller`	`false`	Insert `@WithDocs()` and its import into each controller automatically (opt-in, mutates controller source; idempotent — safe to run repeatedly).

CLI 会自动识别你项目的结构，不需要任何配置：

Layout	Detected when
Simple project	`tsconfig.json` at root, no monorepo markers
Nx monorepo	`nx.json` present
Nest CLI monorepo	`nest-cli.json` with `"monorepo": true`
Generic monorepo	`packages/` or `apps/` with sub-`package.json` files

Scenario	Behavior
Run `generate` on a clean project	Creates all docs files
Run `generate` again (no changes)	Skips all existing files, safe to run repeatedly
Add a new endpoint, run `generate --force`	Merges new method block, preserves existing arrays
Edit a method's decorators, run `--force`	Your edits are preserved
Run `generate --overwrite`	Discards the file entirely, regenerates from scratch

为了方便，可以加进你的 package.json：

json

{
  "scripts": {
    "docs:generate": "nestjs-docfy generate",
    "docs:preview": "nestjs-docfy generate --dry-run"
  }
}