tessl/npm-oas

Comprehensive tooling for working with OpenAPI definitions

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

OAS

Name: tessl/npm-oas
Author: tessl

OAS is a comprehensive TypeScript library for working with OpenAPI definitions. It provides parsing, validation, operation discovery, parameter handling, security analysis, and extensive manipulation tools for OpenAPI 3.0/3.1 specifications. The library is designed for maximum reusability across CLI tools, documentation systems, code generation, request execution, and any application requiring robust OpenAPI definition processing.

Package Information

Package Name: oas
Package Type: npm
Language: TypeScript
Installation: npm install oas

Core Imports

import Oas from "oas";

For CommonJS:

const Oas = require("oas");

Additional imports for specific functionality:

import { Operation, Callback, Webhook } from "oas/operation";
import analyzer from "oas/analyzer";
import reducer from "oas/reducer";
import { findSchemaDefinition, matchesMimeType, supportedMethods, jsonSchemaTypes } from "oas/utils";
import { isRef, isOAS31, isSchema, type OASDocument, type HttpMethods, type SecurityType, type User } from "oas/types";

Basic Usage

import Oas from "oas";

// Load an OpenAPI definition
const oas = new Oas({
  openapi: "3.1.0",
  info: { title: "My API", version: "1.0.0" },
  servers: [{ url: "https://api.example.com" }],
  paths: {
    "/users/{id}": {
      get: {
        operationId: "getUser",
        parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }],
        responses: { "200": { description: "User found" } }
      }
    }
  }
});

// Get server URL
const serverUrl = oas.url(); // "https://api.example.com"

// Find an operation
const operation = oas.operation("/users/{id}", "get");
console.log(operation.getSummary());
console.log(operation.getParameters());

// Get operation by URL
const foundOp = oas.getOperation("https://api.example.com/users/123", "get");
console.log(foundOp?.getOperationId()); // "getUser"

Architecture

OAS is built around several key components:

Core API: Oas class for parsing and manipulating OpenAPI specifications
Operation System: Operation, Callback, and Webhook classes for detailed operation analysis
Discovery Engine: URL-based operation matching and parameter extraction
Type System: Complete TypeScript definitions with full OpenAPI 3.0/3.1 support
Analysis Tools: Feature detection and complexity measurement utilities
Transformation Pipeline: Schema dereferencing, reduction, and manipulation tools

Capabilities

OpenAPI Definition Management

Core functionality for loading, parsing, and accessing OpenAPI definitions with full 3.0/3.1 support.

class Oas {
  constructor(oas: OASDocument | string, user?: User);
  static init(oas: OASDocument | Record<string, unknown>, user?: User): Oas;
  static hasOperationId(schema: OperationObject): boolean;
  static getOperationId(path: string, method: string, schema: OperationObject, opts?: OperationIDGeneratorOptions): string;
  getVersion(): string;
  getDefinition(): OASDocument;
  getPaths(): Record<string, Record<HttpMethods, Operation | Webhook>>;
  getWebhooks(): Record<string, Record<HttpMethods, Webhook>>;
  getTags(setIfMissing?: boolean): string[];
}

OpenAPI Definition Management

Server and URL Management

Server URL handling with variable substitution, templating, and multi-server support.

url(selected?: number, variables?: ServerVariable): string;
variables(selected?: number): ServerVariablesObject;
defaultVariables(selected?: number): ServerVariable;
replaceUrl(url: string, variables?: ServerVariable): string;
splitVariables(baseUrl: string): Servers | false;

Server and URL Management

Operation Discovery and Analysis

Advanced operation discovery by URL, method, operationId, and comprehensive operation analysis.

operation(path: string, method: HttpMethods, opts?: { isWebhook?: boolean }): Operation;
findOperation(url: string, method: HttpMethods): PathMatch;
getOperation(url: string, method: HttpMethods): Operation;
getOperationById(id: string): Operation | Webhook;

Operation Discovery and Analysis

Parameter Handling and JSON Schema

Parameter extraction, JSON Schema conversion, and type-safe parameter processing.

interface Operation {
  getParameters(): ParameterObject[];
  getParametersAsJSONSchema(opts?: getParametersAsJSONSchemaOptions): SchemaWrapper[];
  hasParameters(): boolean;
  hasRequiredParameters(): boolean;
}

Parameter Handling and JSON Schema

Request and Response Management

Comprehensive request body and response handling with content type detection and examples.

interface Operation {
  hasRequestBody(): boolean;
  getRequestBody(mediaType?: string): MediaTypeObject | false | [string, MediaTypeObject, ...string[]];
  getResponseByStatusCode(statusCode: number | string): ResponseObject | boolean;
  getResponseAsJSONSchema(statusCode: number | string, opts?: object): SchemaObject;
}

Request and Response Management

Security and Authentication

Security scheme parsing, authentication handling, and user-based auth token extraction.

interface Operation {
  getSecurity(): SecurityRequirementObject[];
  getSecurityWithTypes(filterInvalid?: boolean): Array<Array<{security: KeyedSecuritySchemeObject, type: SecurityType} | false> | false>;
  prepareSecurity(): Record<SecurityType, KeyedSecuritySchemeObject[]>;
}

getAuth(user: User, selectedApp?: number | string): AuthForHAR;

Security and Authentication

Schema Dereferencing and References

Advanced schema dereferencing with circular reference detection and resolution.

dereference(opts?: {
  cb?: () => void;
  preserveRefAsJSONSchemaTitle?: boolean;
}): Promise<any>;
getCircularReferences(): string[];

Schema Dereferencing and References

Analysis and Metrics

API definition analysis, feature detection, and complexity measurement tools.

function analyzer(definition: OASDocument): Promise<OASAnalysis>;

interface OASAnalysis {
  general: {
    dereferencedFileSize: OASAnalysisGeneral;
    mediaTypes: OASAnalysisGeneral;
    operationTotal: OASAnalysisGeneral;
    rawFileSize: OASAnalysisGeneral;
    securityTypes: OASAnalysisGeneral;
  };
  openapi: Record<string, OASAnalysisFeature>;
  readme: Record<string, OASAnalysisFeature>;
}

Analysis and Metrics

API Definition Reduction

Tools for extracting subsets of large OpenAPI definitions by tags or specific paths.

function reducer(definition: OASDocument, opts?: ReducerOptions): OASDocument;

interface ReducerOptions {
  paths?: Record<string, string[] | '*'>;
  tags?: string[];
}

API Definition Reduction

Extensions and Customization

ReadMe-specific OpenAPI extensions with validation and configuration management.

hasExtension(extension: string): boolean;
getExtension(extension: string | keyof Extensions, operation?: Operation): any;
validateExtension(extension: keyof Extensions): void;
validateExtensions(): void;

Extensions and Customization

Utility Functions

Utility functions for schema manipulation, MIME type detection, and OpenAPI processing.

function findSchemaDefinition(ref: string, api: OASDocument): any;
function matchesMimeType: {
  formUrlEncoded(mimeType: string): boolean;
  json(contentType: string): boolean;
  multipart(contentType: string): boolean;
  wildcard(contentType: string): boolean;
  xml(contentType: string): boolean;
};
const jsonSchemaTypes: Record<keyof OASDocument, string>;
const supportedMethods: readonly string[];

Utility Functions

Types

type OASDocument = (OpenAPIV3_1.Document | OpenAPIV3.Document) & Record<string, unknown>;
type HttpMethods = 'get' | 'put' | 'post' | 'delete' | 'options' | 'head' | 'patch' | 'trace';
type SecurityType = 'apiKey' | 'Basic' | 'Bearer' | 'Cookie' | 'Header' | 'http' | 'OAuth2' | 'Query';

interface User {
  [key: string]: unknown;
  keys?: {
    [key: string]: unknown;
    name: number | string;
    pass?: number | string;
    user?: number | string;
  }[];
}

interface PathMatch {
  match?: Match<ParamData>;
  operation: PathsObject;
  url: {
    method?: HttpMethods;
    nonNormalizedPath: string;
    origin: string;
    path: string;
    slugs: Record<string, string>;
  };
}

interface PathMatches {
  [x: string]: PathMatch[];
}

interface OperationObject {
  operationId?: string;
  summary?: string;
  description?: string;
  tags?: string[];
  deprecated?: boolean;
  security?: SecurityRequirementObject[];
  parameters?: ParameterObject[];
  requestBody?: RequestBodyObject;
  responses: Record<string, ResponseObject>;
  callbacks?: Record<string, CallbackObject>;
}

interface OperationIDGeneratorOptions {
  camelCase?: boolean;
  onlyUseExistingOperationIds?: boolean;
}

interface OASAnalysis {
  general: {
    dereferencedFileSize: OASAnalysisGeneral;
    mediaTypes: OASAnalysisGeneral;
    operationTotal: OASAnalysisGeneral;  
    rawFileSize: OASAnalysisGeneral;
    securityTypes: OASAnalysisGeneral;
  };
  openapi: Record<string, OASAnalysisFeature>;
  readme: Record<string, OASAnalysisFeature>;
}

interface OASAnalysisGeneral {
  found: any;
}

interface OASAnalysisFeature {
  present: boolean;
}

interface ReducerOptions {
  paths?: Record<string, string[] | '*'>;
  tags?: string[];
}

interface AuthForHAR {
  [key: string]: any;
}

interface Servers {
  selected: number;
  variables: ServerVariable;
}

type ServerVariable = Record<
  string,
  { default?: number | string }[] | Record<string, never> | number | string | { default?: number | string }
>;

type OAS31Document = OpenAPIV3_1.Document & Record<string, unknown>;

Install with Tessl CLI

npx tessl i tessl/npm-oas

Workspace: tessl
Visibility: Public
Created: 6 months ago
Last updated: about 1 month ago
Describes: pkg:npm/oas@28.1.x
Publish Source: CLI
Badge