@nest-openapi

OpenAPI‑first utilities for NestJS

Single source of truth · Drop‑in for NestJS · Fast by design

---

Features

• 🎯 Single Source of Truth — Your OpenAPI spec drives validation, serialization, and mocking.
• ⚡ Fast by Design — AJV validation and fast-json-stringify serialization with caching and precompilation.
• 🔌 Drop-in Integration — Works with existing NestJS controllers and routes
• 🎛️ Fine-Grained Control — Per-route opt-out and custom schema overrides
• 🚀 Platform Agnostic — Supports both Express and Fastify adapters

Packages

Package	Description	Version	Docs
@nest-openapi/validator	Automatic request/response validation using your OpenAPI spec		📖 Docs
@nest-openapi/serializer	High-performance response serialization based on your OpenAPI spec		📖 Docs
@nest-openapi/mock	Spec-driven mock server for generating realistic mock responses		📖 Docs

Quick Start

Validator

npm i @nest-openapi/validator

import { Module } from "@nestjs/common";
import { OpenAPIValidatorModule } from "@nest-openapi/validator";
import * as openApiSpec from "./openapi.json";

@Module({
  imports: [
    OpenAPIValidatorModule.forRoot({
      specSource: { type: "object", spec: openApiSpec },
    }),
  ],
})
export class AppModule {}

All routes are automatically validated. See full documentation for advanced configuration.

Serializer

npm i @nest-openapi/serializer

import { Module } from "@nestjs/common";
import { OpenAPISerializerModule } from "@nest-openapi/serializer";
import * as openApiSpec from "./openapi.json";

@Module({
  imports: [
    OpenAPISerializerModule.forRoot({
      specSource: { type: "object", spec: openApiSpec },
      responseSerialization: { enable: true, skipErrorResponses: true },
    }),
  ],
})
export class AppModule {}

Responses are automatically serialized. See full documentation for advanced configuration.

Mock

npm i @nest-openapi/mock

import { Module } from "@nestjs/common";
import { OpenAPIMockModule } from "@nest-openapi/mock";
import * as openApiSpec from "./openapi.json";

@Module({
  imports: [
    OpenAPIMockModule.forRoot({
      specSource: { type: "object", spec: openApiSpec },
      enable: process.env.NODE_ENV === "development",
      mockByDefault: true,
    }),
  ],
})
export class AppModule {}

Routes return mocked responses when enabled. See full documentation for advanced configuration.

Usage Examples

Manual Validation

import { Inject, Injectable } from "@nestjs/common";
import {
  OPENAPI_VALIDATOR,
  OpenAPIValidatorService,
} from "@nest-openapi/validator";

@Injectable()
export class MyService {
  constructor(
    @Inject(OPENAPI_VALIDATOR)
    private readonly validator: OpenAPIValidatorService
  ) {}

  validate(ctx: HttpArgumentsHost) {
    const errors = this.validator.validateRequest(ctx, { body: true });
    if (errors.length > 0) {
      // Handle validation errors
    }
  }
}

Per-Route Overrides

import { Controller, Post } from "@nestjs/common";
import { Validate } from "@nest-openapi/validator";
import { Serialize } from "@nest-openapi/serializer";

@Controller("books")
export class BooksController {
  @Post()
  @Validate({ request: { query: false }, response: true })
  @Serialize({ disable: true })
  create(@Body() dto: CreateBookDto): Book {
    return this.booksService.create(dto);
  }
}

Compatibility

• Works with NestJS v9+
• Supports Express and Fastify adopters

Contributing

Issues and PRs are welcome. Please check the package folders and docs before opening an issue.

License

MIT © @nest-openapi