tessl/npm-swagger-client

SwaggerJS - a collection of interfaces for OAI specs

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Swagger Client

Name: tessl/npm-swagger-client
Author: tessl

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>;
  };
}