Skip to main content

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 sql.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.date()
createdAt: Date;

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

Boolean Fields​

@column.boolean()
isActive: boolean;

Generates: { type: "boolean" }

Numeric Fields​

@column.integer()
age: number;

Generates: { type: "number" }

JSON Fields​

@column.json()
metadata: object;

Generates: { type: "object" }

UUID Fields​

@column.uuid()
id: string;

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

ULID Fields​

@column.ulid()
id: string;

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

OpenAPI Metadata​

You can provide additional OpenAPI metadata in your column decorators:

@column({
  openApi: {
    type: "string",
    description: "User's email address",
    required: true,
  },
})
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"]
}