OpenAPI Generation

Experimental Feature

OpenAPI generation is currently an experimental feature and may undergo breaking changes in future releases. Use with caution in production environments.

Hysteria ORM provides experimental support for automatically generating OpenAPI schemas from your model definitions. This feature allows you to create API documentation and client SDKs directly from your database models.

Overview

The OpenAPI generation feature analyzes your model decorators, TypeScript types, and serialization functions to automatically generate OpenAPI 3.0 compatible schemas. This includes:

• Property types based on column decorators and serialization functions
• Required fields detection from primary keys and non-optional properties
• Format specifications for dates, UUIDs, and other special types
• Property descriptions from OpenAPI metadata

Basic Usage

Generating Schema for a Single Model

import { generateOpenApiModelSchema } from 'hysteria-orm';
import { User } from './models/User';

const userSchema = generateOpenApiModelSchema(User);
console.log(JSON.stringify(userSchema, null, 2));

Generating Schemas for Multiple Models

import { generateOpenApiModel } from 'hysteria-orm';
import { User, Post, Comment } from './models';

const schemas = generateOpenApiModel([User, Post, Comment]);

Generating Schemas with Model Names

import { generateOpenApiModelWithMetadata, sql } from 'hysteria-orm';
import { User, Post } from './models';

const schemasWithNames = generateOpenApiModelWithMetadata([User, Post]);
// Returns array with { modelName: string, ...schema }

// From sql data source
const sql = await SqlDataSource.connect({
  models: {
    user: User,
    post: Post,
  },
});

const schemasWithNames = sql.getModelOpenApiSchema();

Type Detection

The OpenAPI generator automatically detects types based on your model configuration:

Date/Time Fields

@Column({
  serialize: (value) => parseDate(value),
  // ... other options
})
createdAt: string;

Generates: { type: "string", format: "date-time" }

Boolean Fields

@Column({
  serialize: (value) => Boolean(value),
  // ... other options
})
isActive: boolean;

Generates: { type: "boolean" }

Numeric Fields

@Column({
  serialize: (value) => Number(value),
  // ... other options
})
age: number;

Generates: { type: "number" }

JSON Fields

@Column({
  serialize: (value) => JSON.parse(value),
  // ... other options
})
metadata: object;

Generates: { type: "object" }

UUID Fields

@Column({
  prepare: () => randomUUID(),
  // ... other options
})
id: string;

Generates: { type: "string", format: "uuid" }

ULID Fields

@Column({
  prepare: () => generateULID(),
  // ... other options
})
id: string;

Generates: { type: "string", format: "ulid" }

Required Field Detection

The generator automatically determines required fields based on:

• Primary keys - Always marked as required
• Non-hidden fields - Hidden fields are excluded
• Non-auto-update fields - Auto-updating fields are optional
• Non-auto-create fields - Auto-creating fields are optional
• Non-getter/setter properties - Computed properties are optional

OpenAPI Metadata

You can provide additional OpenAPI metadata in your column decorators:

@Column({
  openApiDescription: "User's email address",
  // ... other options
})
email: string;

Example Output

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "Property: id"
    },
    "email": {
      "type": "string",
      "description": "User's email address"
    },
    "age": {
      "type": "number",
      "description": "Property: age"
    },
    "isActive": {
      "type": "boolean",
      "description": "Property: isActive"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "Property: createdAt"
    }
  },
  "required": ["id", "email", "age"]
}

Limitations

Current Limitations

• Experimental API: The interface may change in future releases
• Limited Type Detection: Complex TypeScript types may not be fully detected
• No Validation Rules: OpenAPI validation rules are not yet supported
• No Relations: Related model schemas are not automatically included
• No Custom Formats: Only standard OpenAPI formats are supported