docfy generate
Проходит по проекту и создаёт заготовку *.controller.docs.ts для каждого контроллера. Только статический анализ, код проекта не выполняется.
Использование
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/, apps/, services/, or any dir implied by root package.json's workspaces field (e.g. "workspaces/*"), with sub-package.json files |
generate also checks nest-cli.json's compilerOptions and warns automatically when webpack: true is set without the CLI plugin registered, or the plugin is registered while building with the SWC builder without "typeCheck": true (where it's a silent no-op).
TS project references: if the resolved tsconfig.json is a "solution style" file (only references, no compilerOptions/include of its own) with a single reference, the CLI follows it to the real project automatically. With more than one reference it's ambiguous which one has your controllers, so nothing is guessed — pass --tsconfig pointing at the right one explicitly.
Идемпотентность: --force и --overwrite
| 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 |
npm-скрипт
Для удобства добавьте в package.json:
{
"scripts": {
"docs:generate": "nestjs-docfy generate",
"docs:preview": "nestjs-docfy generate --dry-run"
}
}