or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

client-construction.mdexecution.mdhelpers.mdhttp-client.mdindex.mdrequest-building.mdresolution.md
tile.json

tessl/npm-swagger-client

SwaggerJS - a collection of interfaces for OAI specs

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/swagger-client@3.35.x

To install, run

npx @tessl/cli install tessl/npm-swagger-client@3.35.0

index.mddocs/

Swagger Client

Swagger Client is a comprehensive JavaScript library that enables developers to fetch, resolve, and interact with Swagger/OpenAPI documents. It provides full support for OpenAPI specifications from version 2.0 through 3.1.0, offering capabilities for document resolution, API interaction, and spec validation.

Package Information

  • Package Name: swagger-client
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install swagger-client

Core Imports

import SwaggerClient from "swagger-client";

For CommonJS:

const SwaggerClient = require("swagger-client");

Individual components:

import { 
  execute, 
  buildRequest, 
  resolve, 
  resolveSubtree,
  makeResolve,
  makeResolveSubtree,
  http,
  makeHttp 
} from "swagger-client";

Helper utilities:

import {
  eachOperation,
  findOperation,
  getOperationRaw,
  opId,
  isHttpUrl,
  replaceSpecialCharsWithUnderscore
} from "swagger-client";

For browser UMD builds:

<script src="https://unpkg.com/swagger-client@3.35.6/dist/swagger-client.browser.min.js"></script>

Basic Usage

import SwaggerClient from "swagger-client";

// Initialize client with a Swagger/OpenAPI spec URL
const client = await SwaggerClient({
  url: "https://petstore.swagger.io/v2/swagger.json"
});

// Execute an API operation
const response = await client.execute({
  operationId: "getPetById",
  parameters: {
    petId: 1
  }
});

console.log(response.body);

Architecture

Swagger Client is built around several key components:

  • Main Constructor: Creates client instances with spec resolution and interface generation
  • Resolver System: Multiple strategies for resolving OpenAPI specs with different versions
  • HTTP Client: Customizable HTTP implementation with request/response interceptors
  • Parameter Builders: Version-specific parameter serialization for different OpenAPI versions
  • Interface Generation: Creates convenient tag-based APIs for easier consumption
  • ApiDOM Integration: Advanced parsing and dereferencing capabilities using ApiDOM

Runtime Support

Node.js

  • Requires Node.js >=12.20.0
  • Uses native fetch (>=18) or node-fetch (12.20.0-17.x)

Browsers

  • Chrome, Safari, Firefox, Edge (latest versions)
  • Uses native browser fetch API

Capabilities

Client Construction

Creates SwaggerClient instances with automatic spec resolution and interface generation.

function SwaggerClient(options?: SwaggerClientOptions): Promise<SwaggerClientInstance>;

interface SwaggerClientOptions {
  url?: string;
  spec?: object;
  authorizations?: SecurityAuthorizations;
  requestInterceptor?: RequestInterceptor;
  responseInterceptor?: ResponseInterceptor;
  allowMetaPatches?: boolean;
  useCircularStructures?: boolean;
  http?: HttpClient;
  fetch?: FetchFunction;
  userFetch?: FetchFunction;
  disableInterfaces?: boolean;
  skipNormalization?: boolean;
  pathDiscriminator?: string[];
  v2OperationIdCompatibilityMode?: boolean;
}

interface SwaggerClientInstance {
  spec: object;
  originalSpec?: object;
  errors: ResolutionError[];
  apis: TaggedOperations;
  authorizations?: SecurityAuthorizations;
  execute(options: ExecutionOptions): Promise<ResponseObject>;
  resolve(options?: ResolveOptions): Promise<SwaggerClientInstance>;
}

Client Construction and Configuration

API Execution

Execute operations against OpenAPI specs with parameter handling and security.

function execute(options: ExecutionOptions): Promise<ResponseObject>;

interface ExecutionOptions {
  spec: object;
  operationId?: string;
  pathName?: string;
  method?: string;
  parameters?: ParameterValues;
  securities?: SecurityRequirements;
  requestInterceptor?: RequestInterceptor;
  responseInterceptor?: ResponseInterceptor;
  contextUrl?: string;
  http?: HttpClient;
  fetch?: FetchFunction;
  userFetch?: FetchFunction;
}

interface ResponseObject {
  url: string;
  method: string;
  status: number;
  statusText: string;
  headers: Record<string, string>;
  text: string;
  body: any;
  obj: any;
  ok: boolean;
  data: any;
}

API Execution and Operations

Spec Resolution

Resolve OpenAPI specifications with reference handling and validation.

function resolve(options: ResolveOptions): Promise<ResolutionResult>;

interface ResolveOptions {
  spec?: object;
  url?: string;
  http?: HttpClient;
  fetch?: FetchFunction;
  allowMetaPatches?: boolean;
  useCircularStructures?: boolean;
  requestInterceptor?: RequestInterceptor;
  responseInterceptor?: ResponseInterceptor;
  skipNormalization?: boolean;
  pathDiscriminator?: string[];
}

interface ResolutionResult {
  spec: object;
  errors: ResolutionError[];
}

Spec Resolution and Processing

HTTP Client

Customizable HTTP client with request/response serialization and interceptors.

function http(url: string, options?: HttpOptions): Promise<ResponseObject>;
function makeHttp(httpFn: HttpFunction, preFetch?: Function, postFetch?: Function): HttpFunction;

interface HttpOptions {
  method?: string;
  headers?: Record<string, string>;
  body?: any;
  credentials?: RequestCredentials;
  requestInterceptor?: RequestInterceptor;
  responseInterceptor?: ResponseInterceptor;
  userFetch?: FetchFunction;
  signal?: AbortSignal;
}

HTTP Client and Request Handling

Request Building

Build HTTP requests from OpenAPI operations and parameters.

function buildRequest(options: BuildRequestOptions): RequestObject;

interface BuildRequestOptions {
  spec: object;
  operationId: string;
  parameters?: ParameterValues;
  securities?: SecurityRequirements;
  baseURL?: string;
  contextUrl?: string;
  http?: HttpClient;
  requestInterceptor?: RequestInterceptor;
  responseInterceptor?: ResponseInterceptor;
  userFetch?: FetchFunction;
  signal?: AbortSignal;
}

interface RequestObject {
  url: string;
  method: string;
  headers: Record<string, string>;
  body?: any;
  credentials: RequestCredentials;
}

Request Building and Parameters

Helper Utilities

Utility functions for working with OpenAPI specs and operations.

const SwaggerClient.helpers: {
  opId(operation: OperationObject, pathName: string, method: string, options?: OpIdOptions): string;
};

function eachOperation(spec: object, callback: OperationCallback, find?: boolean): OperationInfo | undefined;
function findOperation(spec: object, predicate: OperationPredicate): OperationInfo | undefined;
function getOperationRaw(spec: object, operationId: string): OperationInfo | undefined;
function opId(operation: OperationObject, pathName: string, method: string, options?: OpIdOptions): string;
function idFromPathMethod(pathName: string, method: string): string;
function idFromPathMethodLegacy(pathName: string, method: string): string;
function isHttpUrl(url: string): boolean;

Helper Utilities and Spec Analysis

Common Types

interface SecurityAuthorizations {
  [securityName: string]: SecurityValue;
}

interface SecurityValue {
  username?: string;
  password?: string;
  clientId?: string;
  clientSecret?: string;
  value?: string;
}

interface ParameterValues {
  [parameterName: string]: any;
}

interface RequestInterceptor {
  (request: RequestObject): RequestObject | Promise<RequestObject>;
}

interface ResponseInterceptor {
  (response: ResponseObject): ResponseObject | Promise<ResponseObject>;
}

interface ResolutionError {
  message: string;
  fullPath: string[];
}

interface TaggedOperations {
  [tagName: string]: {
    [operationId: string]: (parameters?: ParameterValues, options?: ExecutionOptions) => Promise<ResponseObject>;
  };
}