or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

generic-types.mdindex.mdjson-schema.mdopenapi-v2.mdopenapi-v3_1.mdopenapi-v3.md
tile.json

tessl/npm-openapi-types

TypeScript type definitions for OpenAPI documents across all specification versions.

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

To install, run

npx @tessl/cli install tessl/npm-openapi-types@12.1.0

index.mddocs/

OpenAPI Types

OpenAPI Types provides comprehensive TypeScript type definitions for OpenAPI (formerly Swagger) specifications across all major versions. It serves as the de facto standard type library for TypeScript developers working with OpenAPI documents, offering complete type safety and IntelliSense support for API specification parsing, validation, and generation tools.

Package Information

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

Core Imports

import { OpenAPI, OpenAPIV2, OpenAPIV3, OpenAPIV3_1 } from "openapi-types";

For CommonJS:

const { OpenAPI, OpenAPIV2, OpenAPIV3, OpenAPIV3_1 } = require("openapi-types");

Basic Usage

import { OpenAPIV3, OpenAPIV3_1, OpenAPIV2 } from "openapi-types";

// Use version-specific types for targeted OpenAPI support
function processV3Document(doc: OpenAPIV3.Document) {
  console.log(`Processing OpenAPI 3.0 document: ${doc.info.title}`);
  // Access OpenAPI 3.0 specific features
}

function processV31Document(doc: OpenAPIV3_1.Document) {
  console.log(`Processing OpenAPI 3.1 document: ${doc.info.title}`);
  // Access OpenAPI 3.1 specific features like webhooks
  if (doc.webhooks) {
    console.log('Document has webhooks');
  }
}

function processV2Document(doc: OpenAPIV2.Document) {
  console.log(`Processing Swagger 2.0 document: ${doc.info.title}`);
  // Access Swagger 2.0 specific features
}

// Use generic types for version-agnostic code
import { OpenAPI } from "openapi-types";

function processAnyDocument(doc: OpenAPI.Document) {
  // Works with any OpenAPI version
  console.log(`Processing document: ${doc.info.title}`);
}

Architecture

OpenAPI Types is organized around four main namespaces, each providing complete type coverage for their respective OpenAPI specification versions:

  • OpenAPI Namespace: Generic union types that work across all OpenAPI versions
  • OpenAPIV3_1 Namespace: Complete type definitions for OpenAPI 3.1 specification
  • OpenAPIV3 Namespace: Complete type definitions for OpenAPI 3.0 specification
  • OpenAPIV2 Namespace: Complete type definitions for OpenAPI 2.0 (Swagger) specification
  • JSON Schema Support: Base JSON Schema interface used by OpenAPIV2

All types support generic extensions via <T extends {} = {}> parameters, enabling custom extension properties throughout the API surface.

Capabilities

Generic OpenAPI Types

Cross-version union types for building version-agnostic OpenAPI tools and parsers. Ideal for libraries that need to support multiple OpenAPI specification versions.

namespace OpenAPI {
  type Document<T extends {} = {}> = 
    | OpenAPIV2.Document<T>
    | OpenAPIV3.Document<T>
    | OpenAPIV3_1.Document<T>;
  
  type Operation<T extends {} = {}> =
    | OpenAPIV2.OperationObject<T>
    | OpenAPIV3.OperationObject<T>
    | OpenAPIV3_1.OperationObject<T>;
}

Generic OpenAPI Types

OpenAPI 3.1 Types

Complete type definitions for the OpenAPI 3.1 specification with support for JSON Schema 2020-12, webhooks, and enhanced reference objects.

namespace OpenAPIV3_1 {
  interface Document<T extends {} = {}> {
    openapi: string;
    info: InfoObject;
    jsonSchemaDialect?: string;
    servers?: ServerObject[];
    paths?: PathsObject<T>;
    webhooks?: Record<string, PathItemObject | ReferenceObject>;
    components?: ComponentsObject;
    security?: SecurityRequirementObject[];
    tags?: TagObject[];
    externalDocs?: ExternalDocumentationObject;
  }
}

OpenAPI 3.1 Types

OpenAPI 3.0 Types

Complete type definitions for the OpenAPI 3.0 specification, the most widely adopted version of the OpenAPI specification.

namespace OpenAPIV3 {
  interface Document<T extends {} = {}> {
    openapi: string;
    info: InfoObject;
    servers?: ServerObject[];
    paths: PathsObject<T>;
    components?: ComponentsObject;
    security?: SecurityRequirementObject[];
    tags?: TagObject[];
    externalDocs?: ExternalDocumentationObject;
  }
  
  enum HttpMethods {
    GET = 'get',
    PUT = 'put',
    POST = 'post',
    DELETE = 'delete',
    OPTIONS = 'options',
    HEAD = 'head',
    PATCH = 'patch',
    TRACE = 'trace'
  }
}

OpenAPI 3.0 Types

OpenAPI 2.0 Types

Complete type definitions for the OpenAPI 2.0 (Swagger) specification, providing backward compatibility for legacy API specifications.

namespace OpenAPIV2 {
  interface Document<T extends {} = {}> {
    swagger: string;
    info: InfoObject;
    host?: string;
    basePath?: string;
    schemes?: string[];
    consumes?: MimeTypes;
    produces?: MimeTypes;
    paths: PathsObject<T>;
    definitions?: DefinitionsObject;
    parameters?: ParametersDefinitionsObject;
    responses?: ResponsesDefinitionsObject;
    securityDefinitions?: SecurityDefinitionsObject;
    security?: SecurityRequirementObject[];
    tags?: TagObject[];
    externalDocs?: ExternalDocumentationObject;
  }
  
  enum HttpMethods {
    GET = 'get',
    PUT = 'put', 
    POST = 'post',
    DELETE = 'delete',
    OPTIONS = 'options',
    HEAD = 'head',
    PATCH = 'patch'
  }
}

OpenAPI 2.0 Types

JSON Schema Types

Base JSON Schema interface supporting the schema definitions used throughout OpenAPI specifications.

interface IJsonSchema {
  id?: string;
  $schema?: string;
  title?: string;
  description?: string;
  type?: string | string[];
  properties?: { [name: string]: IJsonSchema };
  required?: string[];
  additionalProperties?: boolean | IJsonSchema;
  items?: IJsonSchema | IJsonSchema[];
  enum?: any[];
  allOf?: IJsonSchema[];
  anyOf?: IJsonSchema[];
  oneOf?: IJsonSchema[];
  not?: IJsonSchema;
  $ref?: string;
}

JSON Schema Types