docfy patch-spec

Patches an already-built OpenAPI document, entirely via static analysis (ts-morph), with no require() of any docs file.

Why it exists

This is a manual, CI-driven way to work around the one thing DocfyModule's runtime pipeline structurally cannot do: work under NestJS CLI's webpack: true build mode (see The CLI plugin for the automatic, recommended alternative, which computes this same analysis on every build instead of a separate step). patch-spec sidesteps the webpack wall by matching on path + HTTP method, computed the same way check/coverage/lint already do, instead of needing the live controller class reference.

Usage

bash
npx nestjs-docfy patch-spec --spec <path-or-url> [options]
bash
# Patch a running app's served document
npx nestjs-docfy patch-spec --spec http://localhost:3000/api-json --out openapi.json

# Patch a file already written to disk
npx nestjs-docfy patch-spec --spec dist/openapi.json --out dist/openapi.json

Options

OptionDefaultDescription
--spec <path|url>(required)A local openapi.json, or a URL (e.g. a running app's /api-json)
--out <path>stdoutWhere to write the patched document
--root <path>.Project root directory
--tsconfig <path>auto-detectedPath to tsconfig.json
--pattern <glob>**/*.controller.tsGlob pattern to find controllers
--format <format>tsDocs file format to look for: ts or js
--quietfalseSuppress all output except errors

What gets merged

Matched by path + HTTP method against the base document:

  • ApiTags → unioned into tags (never drops tags the base document already had)
  • ApiOperation({ summary, description, deprecated }) → overwrites those fields
  • ApiResponse({ status, description, schema, example, examples }) → merged per status code (other status codes untouched); when no schema/type is given, falls back to the method's own resolved return type, the same DTO/class-validator/interface inference generate already does, including a oneOf of $refs when the return type is a union of ≥2 named DTOs/entities (e.g. Promise<UserDto | AdminDto>)
  • ApiBody({ schema, examples }) → sets requestBody, with the same return-type-style fallback to the @Body() parameter's resolved type, including the same union → oneOf handling (example is intentionally not read here, since @nestjs/swagger's real ApiBodyOptions type only has examples, unlike ApiResponse, which supports both)
  • ApiBearerAuth() → appended to security
  • ApiParam / ApiQuery / ApiHeader → merged into parameters by name + location: a genuinely new parameter is appended, but one that already exists (e.g. @nestjs/swagger auto-generates a bare required: true entry from reflection alone for any @Query()/@Param()-decorated argument) gets its fields overlaid, not discarded. enum is read from an array literal (enum: ['a', 'b']) or a reference to a TS enum, including one imported from another file (enum: Role), and the schema's type is inferred as number when every resolved value is numeric, string otherwise

What this does not do

Intentionally scoped

This command is intentionally scoped, not a full reimplementation of @nestjs/swagger's decorator semantics: anyOf (no TS construct maps onto "any of" the way a union type naturally maps onto oneOf), links/callbacks (@nestjs/swagger itself has no decorator option for either), and any decorator argument that isn't a literal (a variable, a function call, a spread) are left alone rather than guessed at. It's better to leave a field as the base document already had it than patch in something wrong. A union return type or @Body() payload only becomes a oneOf when every branch resolves to a named DTO/entity. Routes a docs file documents that don't exist in --spec are reported as warnings, not silently dropped or errored on.