Server · OpenAPI

Bind a NestJS server to the schema.

The largest generator. Emits the application-facing boundary and, with the matching options, the validation and response foundation it depends on.

What it emits

Models and DTOsOperation descriptorsOne target-wide shared foundation and per-service Swagger facadesControllersTyped errorsMappersTestsBruno requests

Options

Options this generator adds on top of its base set. Set them under generator: in the target.

Option	Description	Values	Default
`dto`	DTO technology emitted alongside models. Zod DTO constructor constants receive deterministic runtime class names matching their exported symbols, so distinct schemas remain distinct in NestJS and Swagger. `operationContract` needs a value other than `none`.	`none \| zod \| class-validator \| both`	`none`
`operationContract`	Emit one exact operation descriptor and generated `@ContractOperation(Operation)` decorator per route, plus operation-owned named and aggregate parameter metadata. For JSON operations, the decorator invokes native nestjs-zod response metadata and preserves the handler return constraint.	`true \| false`	`false`
`foundation`	Emit exactly one target-wide `shared/http/foundation.ts` with the only `ContractModule`, canonical filter, parameter pipes, and DI-preserving global providers. Each service `http/foundation.ts` re-exports that boundary and keeps only service-specific Swagger configuration and parameter-schema cleanup.	`true \| false`	`false`
`controllers`	Thin generated transport adapters with schema-supported parameter coercion, exact named or aggregate parameter types, and an application-owned port.	`true \| false`	`false`
`errors`	Typed exceptions for documented non-success JSON responses.	`true \| false`	`false`
`mappers`	Explicit one-to-one structural projections, with no inferred business transformations.	`true \| false`	`false`
`tests`	Production-parity test setup, operation manifests, and OpenAPI parity helpers.	`true \| false`	`false`
`bruno`	Bruno requests and a coverage manifest keyed by exact operation identity.	`true \| false`	`false`
`swagger`	Swagger metadata cleaned to match the generated operation surface.	`true \| false`	`false`
`runtime`	Runtime descriptors for the generated operations.	`true \| false`	`false`
`sdk`	A nested SDK that reuses the server-owned models without depending on decorators.	`true \| false`	`false`
`framework`	HTTP adapter the generated foundation targets. Requires the matching `@nestjs/platform-*` package.	`express \| fastify`	`express`
`versioning`	NestJS versioning strategy applied to generated routes and operation metadata. URI route linting supports controller versions, method overrides, VERSION_NEUTRAL, and the generated default.	`uri \| header \| media-type`	`unset`
`defaultVersion`	Version applied when an operation does not declare one.	`string`	`unset`
`envelope`	Wrap successful responses in a fixed shape. Set `dataKey`, and optionally `metaKey`, `staticFields`, and `contextFields` for path and timestamp.	`object`	`unset (no envelope)`
`errorEnvelope`	The default error policy is flat. For nested or custom documented errors, map the complete projection: `bodyKey`, required outer `staticFields`, and the core status/message/type/code/details keys. Requires `errors: true`; `detailsMode` selects structured issues or raw validation output.	`object (detailsMode: issues-object \| raw)`	`unset (flat policy)`
`envelopeDataKey`	Deprecated. Use `envelope.dataKey`; the two cannot be combined.	`string`	`unset`

Shared options

Every OpenAPI generator accepts these, so a schema choice made once stays consistent between a server and its clients.

Option	Description	Values	Default
`audiences`	Apply operation `x-kontract-audiences` policy. `exclude` is validated once against the complete selected OpenAPI source/target universe, not per generated service: siblings with no matching audience generate normally, while a token absent from the whole source fails validation and `generate --clean` preflight before deletion. NestJS may instead set `marker: true` to retain and annotate output.	`object (exclude: string[]; marker: true for typescript-nestjs)`	`unset (operations belong to every audience)`
`zod`	Emit framework-neutral Zod schemas alongside the inferred request and response types.	`true \| false`	`false`
`schemaMode`	How faithfully the source schema is reproduced. `normalize` reshapes inline schemas into named components; `strict` keeps the document as authored.	`normalize \| strict`	`strict for typescript-nestjs, normalize for SDK targets`
`useSingleRequestParameter`	Collapse an operation's parameters into one request object instead of a positional argument list.	`true \| false`	`false`
`stringEnums`	Emit enums as string union types rather than TypeScript `enum` declarations.	`true \| false`	`false`
`enumUnknownDefaultCase`	Add a fallback member so an unrecognised wire value does not throw at the boundary.	`true \| false`	`false`
`modelPropertyNaming`	Casing applied to model properties.	`camelCase \| PascalCase \| snake_case \| original`	`original`
`paramNaming`	Casing applied to operation parameters.	`camelCase \| PascalCase \| snake_case \| original`	`original`
`enumPropertyNaming`	Casing applied to enum members.	`PascalCase \| camelCase \| snake_case \| UPPERCASE \| original`	`original`
`sortModelPropertiesByRequiredFlag`	Order model properties with required ones first.	`true \| false`	`false`
`sortParamsByRequiredFlag`	Order operation parameters with required ones first.	`true \| false`	`false`

Example

type: typescript-nestjsenables

One generated @ContractOperation decorator binds the route, request type, response type, native JSON runtime metadata, and handler return constraint to the same schema operation. The ESLint rule rejects drift and redundant response decorators.

sumr.yamlyaml

targets:
  - name: api-nestjs
    output: ./apps/api/src/contracts
    generator:
      type: typescript-nestjs
      dto: both
      operationContract: true
      sdk: true
      zod: true

recipes.controller.tsts

@Controller('recipes')
export class RecipesController {
  @Get(':recipeId')
  @ContractOperation(GetRecipe)
  getRecipe(@Param('recipeId') recipeId: string): Promise<GetRecipePayload> {
    return this.recipes.getRecipe(recipeId);
  }
}

Prerequisites

Generation fails when one of these is unmet, so check here first when a target stops producing output.

Option	Requires	Conflicts with
`operationContract`	dto other than none	—
`controllers`	foundation: true	—
`tests`	controllers and foundation	—
`errorEnvelope`	errors: true	—
`envelopeDataKey`	—	`envelope`

Options

Shared options

Example

Prerequisites

On this page