Generator

generate() runs the @trapi/metadata extractor over a TypeScript pattern, applies a preset (almost always @routup/swagger-preset), and writes a Swagger / OpenAPI document.

OpenAPI v3

import { generate, Version } from '@routup/swagger';
import process from 'node:process';

await generate({
    version: Version.V3,
    options: {
        metadata: {
            preset: '@routup/swagger-preset',
            entryPoint: {
                cwd: process.cwd(),
                pattern: '**/*.ts',
            },
        },
        output: true,
        outputDirectory: 'writable',
        servers: ['http://localhost:3000/'],
    },
});

The output is written to ./writable/swagger.json.

OpenAPI v2

import { generate, Version } from '@routup/swagger';

await generate({
    version: Version.V2,
    options: {
        metadata: {
            preset: '@routup/swagger-preset',
            entryPoint: { cwd: process.cwd(), pattern: '**/*.ts' },
        },
        output: true,
        outputDirectory: 'writable',
        servers: ['http://localhost:3000/'],
    },
});

Same extraction logic, different document shape. Pick V3 unless you're integrating with a tool that hasn't moved past V2 (rare in 2026).

When to run the generator

• At build time as part of CI, so the generated swagger.json ships with your build artifact
• On startup for development, so the UI reflects code changes without a rebuild

A common split: generate in CI, read in production; regenerate on watch in dev.

See also

• UI — serve the generated document via Swagger UI
• @routup/swagger-preset — what preset: '@routup/swagger-preset' actually does