https://github.com/ts-oas/nest-openapi
A modern, modular set of utilities for building OpenAPI-driven NestJS apps.
https://github.com/ts-oas/nest-openapi
ajv nestjs openapi openapi3 openapi31 validation
Last synced: about 1 month ago
JSON representation
A modern, modular set of utilities for building OpenAPI-driven NestJS apps.
- Host: GitHub
- URL: https://github.com/ts-oas/nest-openapi
- Owner: ts-oas
- License: mit
- Created: 2025-08-13T20:38:07.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2025-12-03T19:33:43.000Z (about 2 months ago)
- Last Synced: 2025-12-07T00:58:41.045Z (about 2 months ago)
- Topics: ajv, nestjs, openapi, openapi3, openapi31, validation
- Language: TypeScript
- Homepage: https://nest-openapi.github.io/
- Size: 238 KB
- Stars: 5
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
@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`](https://www.npmjs.com/package/@nest-openapi/validator) | Automatic request/response validation using your OpenAPI spec | [](https://www.npmjs.com/package/@nest-openapi/validator) | [📖 Docs](https://nest-openapi.github.io/validator/) |
| [`@nest-openapi/serializer`](https://www.npmjs.com/package/@nest-openapi/serializer) | High-performance response serialization based on your OpenAPI spec | [](https://www.npmjs.com/package/@nest-openapi/serializer) | [📖 Docs](https://nest-openapi.github.io/serializer/) |
| [`@nest-openapi/mock`](https://www.npmjs.com/package/@nest-openapi/mock) | Spec-driven mock server for generating realistic mock responses | [](https://www.npmjs.com/package/@nest-openapi/mock) | [📖 Docs](https://nest-openapi.github.io/mock/) |
## Quick Start
### Validator
```bash
npm i @nest-openapi/validator
```
```typescript
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](https://nest-openapi.github.io/validator/) for advanced configuration.
### Serializer
```bash
npm i @nest-openapi/serializer
```
```typescript
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](https://nest-openapi.github.io/serializer/) for advanced configuration.
### Mock
```bash
npm i @nest-openapi/mock
```
```typescript
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](https://nest-openapi.github.io/mock/) for advanced configuration.
## Usage Examples
### Manual Validation
```typescript
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
```typescript
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](https://github.com/ts-oas/nest-openapi)