or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli-interface.mdcore-conversion.mdindex.mdschema-transforms.mdtypescript-utilities.md
tile.json

tessl/npm-openapi-typescript

Convert OpenAPI 3.0 & 3.1 schemas to TypeScript type definitions

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/openapi-typescript@7.9.x

To install, run

npx @tessl/cli install tessl/npm-openapi-typescript@7.9.0

index.mddocs/

OpenAPI TypeScript

OpenAPI TypeScript is a comprehensive TypeScript code generation tool that converts OpenAPI 3.0 and 3.1 schemas into accurate TypeScript type definitions. It provides both a programmatic API and CLI interface, enabling developers to automatically generate type-safe TypeScript interfaces from their OpenAPI specifications with extensive customization options and advanced features.

Package Information

  • Package Name: openapi-typescript
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install openapi-typescript

Core Imports

import openapiTS, { COMMENT_HEADER } from "openapi-typescript";

For CommonJS:

const openapiTS = require("openapi-typescript");

Transform functions:

import { 
  transformSchema,
  transformSchemaObject,
  transformComponentsObject,
  transformPathsObject,
  transformOperationObject,
  astToString
} from "openapi-typescript";

Basic Usage

CLI Usage

# Generate types from local file
openapi-typescript ./api.yaml --output ./types.ts

# Generate types from URL
openapi-typescript https://api.example.com/openapi.json -o ./api-types.ts

# With advanced options
openapi-typescript ./api.yaml \
  --output ./types.ts \
  --export-type \
  --immutable \
  --enum

Programmatic Usage

import openapiTS, { astToString } from "openapi-typescript";
import fs from "node:fs";

// Convert schema to TypeScript AST
const ast = await openapiTS("./api.yaml", {
  exportType: true,
  immutable: true,
  enum: true
});

// Convert AST to TypeScript source code
const output = astToString(ast);

// Write to file
fs.writeFileSync("./types.ts", output);

Architecture

OpenAPI TypeScript is built around several key components:

  • Core Converter: Main openapiTS() function that orchestrates the conversion process
  • Transform Engine: Modular transform functions for each OpenAPI specification object type
  • TypeScript AST Builder: Utilities for creating and manipulating TypeScript AST nodes
  • CLI Interface: Comprehensive command-line tool with extensive configuration options
  • Redocly Integration: Schema validation and bundling using Redocly's OpenAPI core
  • Type System: Complete support for all OpenAPI 3.0/3.1 features with accurate TypeScript mappings

Capabilities

Core Conversion

The main conversion functionality that transforms OpenAPI schemas into TypeScript AST nodes. Supports all input formats and provides extensive customization options.

function openapiTS(
  source: string | URL | OpenAPI3 | Buffer | Readable,
  options?: OpenAPITSOptions
): Promise<ts.Node[]>;

interface OpenAPITSOptions {
  additionalProperties?: boolean;
  alphabetize?: boolean;
  arrayLength?: boolean;
  defaultNonNullable?: boolean;
  emptyObjectsUnknown?: boolean;
  enum?: boolean;
  enumValues?: boolean;
  dedupeEnums?: boolean;
  excludeDeprecated?: boolean;
  exportType?: boolean;
  immutable?: boolean;
  rootTypes?: boolean;
  rootTypesNoSchemaPrefix?: boolean;
  pathParamsAsTypes?: boolean;
  propertiesRequiredByDefault?: boolean;
  inject?: string;
  transform?: (schemaObject: SchemaObject, metadata: TransformNodeOptions) => ts.TypeNode;
  postTransform?: (ast: ts.Node[]) => ts.Node[];
  makePathsEnum?: boolean;
  generatePathParams?: boolean;
  silent?: boolean;
  cwd?: string | URL;
  redocly?: Config;
}

const COMMENT_HEADER: string;

Core Conversion

Schema Transforms

Transform functions for converting individual OpenAPI objects to TypeScript AST nodes. Essential for custom processing and advanced integrations.

function transformSchema(schema: OpenAPI3, ctx: GlobalContext): ts.Node[];

function transformSchemaObject(
  schemaObject: SchemaObject | ReferenceObject,
  options: TransformNodeOptions
): ts.TypeNode;

function transformComponentsObject(
  componentsObject: ComponentsObject,
  ctx: GlobalContext
): ts.Node[];

function transformPathsObject(
  pathsObject: PathsObject,
  ctx: GlobalContext
): ts.TypeNode;

Schema Transforms

TypeScript AST Utilities

Comprehensive utilities for creating and manipulating TypeScript AST nodes. Provides building blocks for custom transform functions and AST manipulation.

function astToString(
  ast: ts.Node[], 
  options?: AstToStringOptions
): string;

function stringToAST(source: string): unknown[];

function tsLiteral(value: unknown): ts.TypeNode;
function tsUnion(types: ts.TypeNode[]): ts.TypeNode;
function tsIntersection(types: ts.TypeNode[]): ts.TypeNode;

interface AstToStringOptions {
  formatOptions?: FormatCodeSettings;
  banner?: string;
  footer?: string;
}

TypeScript AST Utilities

CLI Interface

Complete command-line interface with extensive configuration options for integration into build processes and development workflows.

// CLI Options Interface (conceptual representation)
interface CLIOptions {
  help?: boolean;
  version?: boolean;
  output?: string;
  redocly?: string;
  check?: boolean;
  exportType?: boolean;
  immutable?: boolean;
  enum?: boolean;
  enumValues?: boolean;
  dedupeEnums?: boolean;
  additionalProperties?: boolean;
  emptyObjectsUnknown?: boolean;
  defaultNonNullable?: boolean;
  propertiesRequiredByDefault?: boolean;
  arrayLength?: boolean;
  pathParamsAsTypes?: boolean;
  alphabetize?: boolean;
  excludeDeprecated?: boolean;
  rootTypes?: boolean;
  rootTypesNoSchemaPrefix?: boolean;
  makePathsEnum?: boolean;
}

CLI Interface

Types

Core TypeScript type definitions for OpenAPI specification objects and configuration options.

interface OpenAPI3 {
  openapi: string;
  info: InfoObject;
  jsonSchemaDialect?: string;
  servers?: ServerObject[];
  paths?: PathsObject;
  webhooks?: { [id: string]: PathItemObject | ReferenceObject };
  components?: ComponentsObject;
  security?: SecurityRequirementObject[];
  tags?: TagObject[];
  externalDocs?: ExternalDocumentationObject;
  $defs?: $defs;
}

interface GlobalContext {
  additionalProperties: boolean;
  alphabetize: boolean;
  arrayLength: boolean;
  defaultNonNullable: boolean;
  discriminators: Map<string, DiscriminatorObject>;
  emptyObjectsUnknown: boolean;
  enum: boolean;
  enumValues: boolean;
  dedupeEnums: boolean;
  excludeDeprecated: boolean;
  exportType: boolean;
  immutable: boolean;
  rootTypes: boolean;
  rootTypesNoSchemaPrefix: boolean;
  pathParamsAsTypes: boolean;
  propertiesRequiredByDefault: boolean;
  makePathsEnum: boolean;
  generatePathParams: boolean;
  silent: boolean;
  resolve(ref: string): any;
}

interface TransformNodeOptions {
  path: string;
  ctx: GlobalContext;
  schema: OpenAPI3;
}