InversifyJS + OpenAPI: One Schema to Validate Them All

Here's a situation you've probably been in before:

# Your OpenAPI spec says this:
requestBody:
  content:
    application/json:
      schema:
        type: object
        required: [name, email]
        properties:
          name: { type: string, minLength: 1 }
          email: { type: string, format: email }

// Your validation layer says this:
const schema = z.object({
  name: z.string().min(1),
  email: z.string().email(),
});

Two definitions of the same shape. They start identical. Then someone updates the OpenAPI spec but forgets the Zod schema. Or vice versa. A week later, your Swagger UI shows one contract and your server enforces a completely different one.

There's a better way.

Your OpenAPI Spec Is Already Your Schema

That's the core idea behind @inversifyjs/open-api-validation. If you're using InversifyJS and already decorating your controllers with @OasRequestBody, you've already written your validation schema — you just didn't know it.

The pipe reads the OpenAPI schemas from your @inversifyjs/http-open-api decorators, compiles them with Ajv, and validates incoming requests automatically. Zero extra schema definitions. Zero drift.

A Complete Example

Here's a real controller — name required with a minimum length, email required with format validation:

import { Controller, Post } from '@inversifyjs/http-core';
import { InversifyExpressHttpAdapter } from '@inversifyjs/http-express';
import { OasRequestBody, SwaggerUiProvider } from '@inversifyjs/http-open-api';
import { InversifyValidationErrorFilter } from '@inversifyjs/http-validation';
import { type OpenApi3Dot1Object } from '@inversifyjs/open-api-types/v3Dot1';
import { ValidatedBody } from '@inversifyjs/open-api-validation';
import { OpenApiValidationPipe } from '@inversifyjs/open-api-validation/v3Dot1';
import { Container } from 'inversify';

const container = new Container();

const openApiObject: OpenApi3Dot1Object = {
  info: { title: 'My API', version: '1.0.0' },
  openapi: '3.1.1',
};

const swaggerProvider = new SwaggerUiProvider({
  api: { openApiObject, path: '/docs' },
});

interface User {
  email: string;
  name: string;
}

@Controller('/users')
class UserController {
  @OasRequestBody({
    content: {
      'application/json': {
        schema: {
          additionalProperties: false,
          properties: {
            email: { format: 'email', type: 'string' },
            name: { minLength: 1, type: 'string' },
          },
          required: ['name', 'email'],
          type: 'object',
        },
      },
    },
  })
  @Post('/')
  public createUser(@ValidatedBody() user: User): string {
    return `Created user: ${user.name}`;
  }
}

container.bind(InversifyValidationErrorFilter).toSelf().inSingletonScope();
container.bind(UserController).toSelf().inSingletonScope();

// Merges @OasRequestBody metadata into the OpenAPI document
swaggerProvider.provide(container);

const adapter = new InversifyExpressHttpAdapter(container);

// The pipe receives the fully populated spec — no separate schema file
adapter.useGlobalPipe(new OpenApiValidationPipe(swaggerProvider.openApiObject));
adapter.useGlobalFilters(InversifyValidationErrorFilter);

The @OasRequestBody decorator defines the contract. @ValidatedBody() marks the parameter for validation. OpenApiValidationPipe bridges the two. That's the entire setup.

What Happens When Validation Fails

Send a body with an unknown field (the schema uses additionalProperties: false):

POST /users
Content-Type: application/json

{ "name": "Alice", "email": "alice@example.com", "role": "admin" }

Response:

HTTP/1.1 400 Bad Request

{
  "message": "[schema: #/additionalProperties, instance: ]: \"must NOT have additional properties\""
}

Send an invalid email:

HTTP/1.1 400 Bad Request

{
  "message": "[schema: #/properties/email/format, instance: /email]: \"must match format \\\"email\\\"\""
}

The error points directly to the failing schema path and instance path — no digging required. InversifyValidationErrorFilter catches the InversifyValidationError thrown by the pipe and returns the 400 automatically.

Query Parameter Validation Too

Body validation is only part of the story. Query parameters are just as common a source of bugs — and the same duplication problem applies. With @ValidatedQuery(), the pipe validates query params against the schemas defined in your @OasParameter({ in: 'query' }) decorators:

import { Controller, Get } from '@inversifyjs/http-core';
import { OasParameter } from '@inversifyjs/http-open-api';
import { ValidatedQuery } from '@inversifyjs/open-api-validation';

interface ProductQuery {
  limit?: number;
  search?: string;
}

@Controller('/products')
class ProductController {
  @OasParameter({
    in: 'query',
    name: 'search',
    required: false,
    schema: { type: 'string' },
  })
  @OasParameter({
    in: 'query',
    name: 'limit',
    required: false,
    schema: { minimum: 1, type: 'integer' },
  })
  @Get('/')
  public getProducts(@ValidatedQuery() query: ProductQuery): string {
    return `Search: ${query.search ?? ''}`;
  }
}

Send GET /products?limit=not-a-number and you get:

{
  "message": "[query: limit, schemaPath: #/type, instancePath: ]: \"must be integer\""
}

Query string values are automatically coerced to the declared type before validation — a ?limit=10 string becomes the number 10 before Ajv ever sees it.

Path parameters and headers work the same way with @ValidatedParams() and @ValidatedHeaders().

How It Compares to the Typical Approach

	Typical	`open-api-validation`
Schema definition	Separate (Zod, Yup, Ajv…)	`@OasRequestBody` / `@OasParameter`
OpenAPI spec	Written separately or generated	Written once, used for both
Drift risk	High — two files to keep in sync	None — one source of truth
Error details	Depends on library	Ajv schema path + instance path
Adoption	All-or-nothing	Per-parameter — add `@ValidatedBody()` / `@ValidatedQuery()` where you want it

How It Works Under the Hood

swaggerProvider.provide(container) scans controller metadata and merges @OasRequestBody and @OasParameter data into the OpenAPI document.
OpenApiValidationPipe receives the fully populated spec and uses JSON Pointer resolution to find the schema for each operation.
Schemas are compiled into Ajv validators on first use and cached — cold starts only pay the compilation cost once.
The compiled validator runs against the incoming request. On failure, an InversifyValidationError is thrown with full Ajv error details.

OpenAPI 3.1 and 3.2

Both versions are supported through dedicated subpath exports:

// Decorators work the same for both versions
import { ValidatedBody, ValidatedHeaders, ValidatedQuery, ValidatedParams } from '@inversifyjs/open-api-validation';

// Pick the version matching your spec
import { OpenApiValidationPipe } from '@inversifyjs/open-api-validation/v3Dot1';
import { OpenApiValidationPipe } from '@inversifyjs/open-api-validation/v3Dot2';

Getting Started

npm install @inversifyjs/open-api-validation ajv ajv-formats

If you're already using @inversifyjs/http-open-api to document your API, adding body validation is a five-minute change. You're writing the schemas anyway — stop writing them twice.

Full documentation: https://inversify.io/framework/validation/openapi/introduction/
Source: github.com/inversify/monorepo

Have feedback or questions? Open an issue on GitHub or drop a comment below.

推荐订阅源

DEV Community