or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

common-utilities.mdindex.mdopenapi-v2-types.mdopenapi-v3-types.mdworkspace-management.md
tile.json

tessl/npm-azure-tools--openapi

Library providing types for OpenAPI 2.0 and OpenAPI 3.0 as well as some utilities to manipulate those documents.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@azure-tools/openapi@3.6.x

To install, run

npx @tessl/cli install tessl/npm-azure-tools--openapi@3.6.0

index.mddocs/

@azure-tools/openapi

A comprehensive TypeScript library providing strongly-typed interfaces and utilities for working with OpenAPI 2.0 (Swagger) and OpenAPI 3.0 specification documents. This library offers complete type definitions for all OpenAPI components, reference resolution, extension property handling, and workspace utilities for multi-file OpenAPI documents.

Package Information

  • Package Name: @azure-tools/openapi
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @azure-tools/openapi

Core Imports

import { OpenAPI3Document, dereference, isReference } from "@azure-tools/openapi";
import { createOpenAPIWorkspace } from "@azure-tools/openapi";

For OpenAPI v2 specific types:

import { OpenAPI2Document, OpenAPI2Operation } from "@azure-tools/openapi/v2";

For OpenAPI v3 specific types:

import { OpenAPI3Document, Schema, Parameter } from "@azure-tools/openapi/v3";

CommonJS:

const { OpenAPI3Document, dereference, createOpenAPIWorkspace } = require("@azure-tools/openapi");
const { OpenAPI2Document } = require("@azure-tools/openapi/v2");

Basic Usage

import { OpenAPI3Document, dereference, isReference } from "@azure-tools/openapi";

// Working with OpenAPI 3.0 documents
const document: OpenAPI3Document = {
  openapi: "3.0.0",
  info: { title: "My API", version: "1.0.0" },
  paths: {
    "/users": {
      get: {
        responses: {
          "200": {
            description: "Success",
            content: {
              "application/json": {
                schema: { $ref: "#/components/schemas/User" }
              }
            }
          }
        }
      }
    }
  },
  components: {
    schemas: {
      User: {
        type: "object",
        properties: {
          id: { type: "integer" },
          name: { type: "string" }
        }
      }
    }
  }
};

// Resolve references
const userSchemaRef = document.paths["/users"]?.get?.responses["200"]?.content?.["application/json"]?.schema;

if (userSchemaRef && isReference(userSchemaRef)) {
  const resolved = dereference(document, userSchemaRef);
  console.log(resolved.instance); // The actual User schema object
  console.log(resolved.name); // "User"
}

Architecture

The @azure-tools/openapi library is structured around several key components:

  • Type System: Complete TypeScript definitions for OpenAPI 2.0 and 3.0 specifications
  • Reference Resolution: Utilities for resolving $ref references with circular dependency detection
  • Extension Handling: Proper typing and utilities for working with x-* extension properties
  • Workspace Management: Multi-file OpenAPI document handling with cross-file reference resolution
  • Format Support: Dual support for both OpenAPI 2.0 (Swagger) and OpenAPI 3.0 formats
  • Utility Functions: Helper functions for common OpenAPI document manipulation tasks

Capabilities

Common Utilities

Core utilities for working with OpenAPI documents including reference resolution, extension property handling, and type guards.

function dereference<T extends {} | undefined>(
  document: any,
  item: Refable<T>,
  stack?: string[]
): Dereferenced<T>;

function isReference<T extends {} | undefined>(item: Refable<T>): item is PathReference;

function isExtensionKey(key: string | ExtensionKey): key is ExtensionKey;

Common Utilities

OpenAPI v2 Types

Complete type definitions for OpenAPI 2.0 (Swagger) specification including documents, operations, parameters, and definitions.

interface OpenAPI2Document {
  swagger: "2.0";
  host?: string;
  basePath?: string;
  paths: { [path: string]: OpenAPI2Path };
  definitions: { [name: string]: OpenAPI2Definition };
}

interface OpenAPI2Operation {
  operationId: string;
  description: string;
  responses: OpenAPI2OperationResponses;
  parameters?: Refable<OpenAPI2Parameter>[];
}

OpenAPI v2 Types

OpenAPI v3 Types

Complete type definitions for OpenAPI 3.0 specification including documents, components, operations, schemas, and security definitions.

interface OpenAPI3Document extends Extensions {
  openapi: string;
  info: Info;
  paths: Dictionary<PathItem>;
  components?: Components;
  servers?: Array<Server>;
}

interface Schema extends Deprecatable, Extensions {
  type?: EnumStr<JsonType>;
  properties?: Dictionary<PropertyReference<Schema>>;
  required?: Array<string>;
  items?: Refable<Schema>;
}

OpenAPI v3 Types

Workspace Management

Multi-file OpenAPI document workspace with cross-file reference resolution and validation.

function createOpenAPIWorkspace<T extends OpenAPI2Document | OpenAPI3Document>(
  workspace: WorkspaceConfig<T>
): OpenAPIWorkspace<T>;

interface OpenAPIWorkspace<T extends OpenAPI2Document | OpenAPI3Document> {
  specs: Map<string, T>;
  resolveReference<T>(args: ResolveReferenceArgs): T;
}

Workspace Management

Types

type Refable<T extends {} | undefined> = T | PathReference;

interface PathReference {
  $ref: string;
}

interface Dereferenced<T> {
  instance: T;
  name: string;
  fromRef?: boolean;
}

type ExtensionKey = `x-${string}`;

type Extensions = {
  [key in ExtensionKey]: any;
};

type Dictionary<T> = { [key: string]: T };