OpenAPI

Zelt automatically generates OpenAPI 3.1 specifications from your controllers — no decorators or annotations required.

Overview

The @zeltjs/openapi package analyzes your controller method signatures at build time and generates a standard OpenAPI 3.1 specification.

Installation

npm

npm install @zeltjs/openapi

pnpm

pnpm add @zeltjs/openapi

bun

bun add @zeltjs/openapi

@zeltjs/validator-valibot と併用する場合

@zeltjs/validator-valibot を使っている場合、@valibot/to-json-schema も必要です：

npm

npm install @zeltjs/openapi @valibot/to-json-schema

pnpm

pnpm add @zeltjs/openapi @valibot/to-json-schema

bun

bun add @zeltjs/openapi @valibot/to-json-schema

:::tip バージョン互換性 @valibot/to-json-schema は valibot のバージョンと合わせる必要があります。詳細は Validation - Installation を参照してください。 :::

Configuration

Create a zelt.config.ts file in your project root:

export default defineConfig({
  controllers: ['./src/**/*.controller.ts'],
  dist: './generated',
  tsconfig: './tsconfig.json',
});

Configuration Options

Option	Type	Description
controllers	string[]	Glob patterns to find controller files
dist	string	Output directory for generated files
tsconfig	string	Path to tsconfig.json (required for OpenAPI generation)

Controllers are automatically discovered by scanning files matching the glob patterns and detecting classes with @Controller decorator.

Generating OpenAPI Spec

One-time Build

pnpm zelt-openapi build

This generates <dist>/openapi.json.

Watch Mode

pnpm zelt-openapi watch

Continuously regenerates when controllers change.

npm Scripts

Add to your package.json:

{
  "scripts": {
    "generate": "zelt-openapi build",
    "generate:watch": "zelt-openapi watch"
  }
}

Generated openapi.json

Standard OpenAPI 3.1 specification:

{
  "openapi": "3.1.0",
  "info": {
    "title": "zelt app",
    "version": "0.0.0"
  },
  "paths": {
    "/hello/{name}": {
      "get": {
        "parameters": [...],
        "responses": {...}
      }
    }
  },
  "components": {
    "schemas": {...}
  }
}

How It Works

Zelt uses a "zero-annotation" approach inspired by Scramble:

1. Static Analysis — Analyzes controller method signatures at build time
2. Type Extraction — Extracts request/response types from TypeScript types
3. Schema Generation — Converts TypeScript types to JSON Schema for OpenAPI

This means your runtime code stays clean — no decorators or schema definitions needed beyond what you already write for validation.