or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdopenapi30-builder.mdopenapi30-types.mdopenapi31-builder.mdopenapi31-types.mdserver-management.mdspecification-extensions.md
tile.json

tessl/npm-openapi3-ts

TypeScript models and utilities for building OpenAPI 3.x specification documents with fluent DSL builder pattern

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/openapi3-ts@4.5.x

To install, run

npx @tessl/cli install tessl/npm-openapi3-ts@4.5.0

index.mddocs/

OpenAPI3-TS

OpenAPI3-TS is a comprehensive TypeScript library providing typed models and utilities for building OpenAPI 3.x specification documents. It offers complete support for both OpenAPI 3.0 and 3.1 specifications with a fluent DSL builder pattern, enabling type-safe programmatic creation of OpenAPI contracts from scratch.

Package Information

  • Package Name: openapi3-ts
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install openapi3-ts

Core Imports

import { oas30, oas31, Server, ServerVariable } from "openapi3-ts";

For version-specific imports:

import { OpenApiBuilder } from "openapi3-ts/oas30";
import { OpenApiBuilder } from "openapi3-ts/oas31";

For CommonJS:

const { oas30, oas31, Server, ServerVariable } = require("openapi3-ts");

Basic Usage

import { oas30 } from "openapi3-ts";

// Create a new OpenAPI 3.0 document
const builder = oas30.OpenApiBuilder.create()
  .addTitle("Pet Store API")
  .addVersion("1.0.0")
  .addDescription("A sample API for managing pets")
  .addPath("/pets", {
    get: {
      summary: "List all pets",
      responses: {
        "200": {
          description: "A list of pets",
          content: {
            "application/json": {
              schema: {
                type: "array",
                items: { $ref: "#/components/schemas/Pet" }
              }
            }
          }
        }
      }
    }
  })
  .addSchema("Pet", {
    type: "object",
    required: ["id", "name"],
    properties: {
      id: { type: "integer", format: "int64" },
      name: { type: "string" },
      tag: { type: "string" }
    }
  });

// Export as JSON or YAML
const spec = builder.getSpec();
const json = builder.getSpecAsJson(null, 2);
const yaml = builder.getSpecAsYaml();

Architecture

OpenAPI3-TS is built around several key components:

  • Dual OpenAPI Support: Separate namespaces (oas30, oas31) with complete OpenAPI 3.0 and 3.1 specification coverage
  • Fluent Builder Pattern: OpenApiBuilder class providing chainable method calls for programmatic document construction
  • Type Safety: Comprehensive TypeScript interfaces covering all OpenAPI specification components
  • Extension Support: Full support for OpenAPI specification extensions (x-* properties)
  • Multi-Format Export: Built-in JSON and YAML serialization capabilities
  • Zero Dependencies: Only requires yaml for YAML processing, no other external dependencies

Capabilities

OpenAPI 3.0 Builder

Fluent DSL for creating OpenAPI 3.0 specification documents with complete type safety and chainable operations.

class OpenApiBuilder {
  static create(doc?: oas30.OpenAPIObject): OpenApiBuilder;
  getSpec(): oas30.OpenAPIObject;
  getSpecAsJson(replacer?: (key: string, value: unknown) => unknown, space?: string | number): string;
  getSpecAsYaml(replacer?: Parameters<typeof yaml.stringify>[1], options?: Parameters<typeof yaml.stringify>[2]): string;
}

OpenAPI 3.0 Builder

OpenAPI 3.1 Builder

Fluent DSL for creating OpenAPI 3.1 specification documents with enhanced JSON Schema support and webhook capabilities.

class OpenApiBuilder {
  static create(doc?: oas31.OpenAPIObject): OpenApiBuilder;
  addWebhook(webhook: string, webhookItem: oas31.PathItemObject): OpenApiBuilder;
}

OpenAPI 3.1 Builder

OpenAPI 3.0 Type System

Complete TypeScript interfaces for all OpenAPI 3.0 specification components including schemas, operations, and security.

interface OpenAPIObject extends ISpecificationExtension {
  openapi: string;
  info: InfoObject;
  servers?: ServerObject[];
  paths: PathsObject;
  components?: ComponentsObject;
  security?: SecurityRequirementObject[];
  tags?: TagObject[];
  externalDocs?: ExternalDocumentationObject;
}

OpenAPI 3.0 Types

OpenAPI 3.1 Type System

Enhanced TypeScript interfaces for OpenAPI 3.1 with JSON Schema Draft 2020-12 support and webhook definitions.

interface OpenAPIObject extends ISpecificationExtension {
  openapi: string;
  info: InfoObject;
  servers?: ServerObject[];
  paths?: PathsObject;
  components?: ComponentsObject;
  security?: SecurityRequirementObject[];
  tags?: TagObject[];
  externalDocs?: ExternalDocumentationObject;
  webhooks?: PathsObject;
}

OpenAPI 3.1 Types

Server Management

Classes for defining and managing OpenAPI server configurations with variable support and extension capabilities.

class Server implements ServerObject {
  constructor(url: string, desc?: string);
  addVariable(name: string, variable: ServerVariable): void;
  url: string;
  description?: string;
  variables: { [v: string]: ServerVariable };
}

class ServerVariable implements ServerVariableObject {
  constructor(defaultValue: string | boolean | number, enums?: string[] | boolean[] | number[], description?: string);
  enum?: string[] | boolean[] | number[];
  default: string | boolean | number;
  description?: string;
}

Server Management

Specification Extensions

Support for OpenAPI specification extensions (x-* properties) with validation and management utilities.

type IExtensionName = `x-${string}`;
type IExtensionType = any;

interface ISpecificationExtension {
  [extensionName: IExtensionName]: IExtensionType;
}

class SpecificationExtension implements ISpecificationExtension {
  static isValidExtension(extensionName: string): boolean;
  getExtension(extensionName: string): any;
  addExtension(extensionName: string, payload: any): void;
  listExtensions(): string[];
}

Specification Extensions

Common Types

interface InfoObject extends ISpecificationExtension {
  title: string;
  description?: string;
  termsOfService?: string;
  contact?: ContactObject;
  license?: LicenseObject;
  version: string;
}

interface ContactObject extends ISpecificationExtension {
  name?: string;
  url?: string;
  email?: string;
}

interface LicenseObject extends ISpecificationExtension {
  name: string;
  url?: string;
}

interface ServerObject extends ISpecificationExtension {
  url: string;
  description?: string;
  variables?: { [v: string]: ServerVariableObject };
}

interface ServerVariableObject extends ISpecificationExtension {
  enum?: string[] | boolean[] | number[];
  default: string | boolean | number;
  description?: string;
}

interface ReferenceObject {
  $ref: string;
}

interface ExternalDocumentationObject extends ISpecificationExtension {
  description?: string;
  url: string;
}