Spec Validation

Every generated spec is checked for missing $ref targets and against the official OpenAPI schema for its version. When either check fails, the spec is still written, result.validation.valid is false, and the CLI prints the problems and exits with code 1.

validateSpec()

function validateSpec(spec: OpenApiSpec): ValidationResult;

Returns a summary of total refs, broken refs, and missing schema names.

import { generate, formatValidationResult } from 'nestjs-openapi';

const result = await generate('./openapi.config.ts');

if (!result.validation.valid) {
  console.warn(formatValidationResult(result.validation));
}

validateStructure()

function validateStructure(
  spec: OpenApiSpec,
): Promise<readonly StructuralError[]>;

Checks a spec against the official OpenAPI 3.0, 3.1 or 3.2 schema, and for 3.0 also the rule that schema cannot express: nullable needs a type beside it. Each error has a JSON pointer path and a message. generate() puts them in result.validation.structuralErrors.

formatValidationResult()

function formatValidationResult(result: ValidationResult): string;

Formats a readable summary suitable for CLI output: structural errors, then broken refs by category (primitive types, union types, query/path params, and other missing schemas).

categorizeBrokenRefs()

function categorizeBrokenRefs(
  missingSchemas: ReadonlyMap<string, number>,
): BrokenRefCategories;

Groups missing schema names to help diagnose where refs are coming from.

Related Types

See the full type definitions in Types.