tessl/npm-swagger-client

SwaggerJS - a collection of interfaces for OAI specs

—

Pending

Overview

Eval results

Files

Request Building and Parameters

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

Build HTTP requests from OpenAPI operations and parameters with version-specific handling for different spec formats.

Capabilities

Build Request Function

Build HTTP request objects from OpenAPI operation parameters.

/**
 * Build HTTP request from OpenAPI operation
 * @param options - Request building options
 * @returns HTTP request object ready for execution
 */
function buildRequest(options: BuildRequestOptions): RequestObject;

interface BuildRequestOptions {
  /** OpenAPI specification object */
  spec: object;
  /** Operation ID to build request for */
  operationId: string;
  /** Parameter values for the operation */
  parameters?: ParameterValues;
  /** Security requirements and credentials */
  securities?: SecurityRequirements;
  /** Base URL override */
  baseURL?: string;
  /** Context URL for relative URL resolution */
  contextUrl?: string;
  /** Server URL override (OpenAPI 3.x) */
  server?: string;
  /** Server variable values (OpenAPI 3.x) */
  serverVariables?: Record<string, string>;
  /** Custom HTTP client */
  http?: HttpClient;
  /** Function to intercept requests */
  requestInterceptor?: RequestInterceptor;
  /** Function to intercept responses */
  responseInterceptor?: ResponseInterceptor;
  /** Custom fetch implementation */
  userFetch?: FetchFunction;
  /** AbortSignal for request cancellation */
  signal?: AbortSignal;
  /** URL scheme override (Swagger 2.0) */
  scheme?: string;
  /** Response content type preference */
  responseContentType?: string;
  /** Custom parameter builders */
  parameterBuilders?: ParameterBuilders;
  /** Server variable encoder function */
  serverVariableEncoder?: (value: string) => string;
}

interface RequestObject {
  /** Request URL with parameters applied */
  url: string;
  /** HTTP method */
  method: string;
  /** Request headers */
  headers: Record<string, string>;
  /** Request body */
  body?: any;
  /** Request credentials policy */
  credentials: RequestCredentials;
  /** AbortSignal for cancellation */
  signal?: AbortSignal;
  /** Request interceptor */
  requestInterceptor?: RequestInterceptor;
  /** Response interceptor */
  responseInterceptor?: ResponseInterceptor;
  /** Custom fetch function */
  userFetch?: FetchFunction;
}

Usage Examples:

import { buildRequest } from "swagger-client";

// Build request for operation
const request = buildRequest({
  spec: openApiSpec,
  operationId: "getUserById",
  parameters: {
    userId: "123",
    include: ["profile", "settings"]
  }
});
console.log(request.url); // https://api.example.com/users/123?include=profile&include=settings

// Build request with custom base URL
const request = buildRequest({
  spec: openApiSpec,
  operationId: "createUser",
  baseURL: "https://api-staging.example.com",
  parameters: {
    body: {
      name: "John Doe",
      email: "john@example.com"
    }
  }
});

// Build request with security
const request = buildRequest({
  spec: openApiSpec,
  operationId: "getProtectedData",
  securities: {
    authorized: {
      ApiKeyAuth: { value: "your-api-key" }
    }
  }
});
console.log(request.headers.Authorization); // Bearer your-api-key

Parameter Handling

Handle different parameter types and locations for both OpenAPI versions.

interface ParameterValues {
  /** Parameter values by name */
  [parameterName: string]: any;
  /** Alternative format: parameter values by location and name */
  [locationAndName: string]: any; // e.g., "query.limit", "header.authorization"
}

interface ParameterBuilders {
  /** Build path parameters */
  path?: ParameterBuilder;
  /** Build query parameters */
  query?: ParameterBuilder;
  /** Build header parameters */
  header?: ParameterBuilder;
  /** Build cookie parameters (OpenAPI 3.x) */
  cookie?: ParameterBuilder;  
  /** Build form data parameters (Swagger 2.0) */
  formData?: ParameterBuilder;
  /** Build request body (Swagger 2.0) */
  body?: ParameterBuilder;
}

interface ParameterBuilder {
  (options: ParameterBuildOptions): void;
}

interface ParameterBuildOptions {
  /** Request object being built */
  req: RequestObject;
  /** Parameter definition from spec */
  parameter: ParameterObject;
  /** Parameter value */
  value: any;
  /** Operation object */
  operation: OperationObject;
  /** Full OpenAPI spec */
  spec: object;
  /** Base URL being used */
  baseURL: string;
}

Path Parameters

Replace path templates with parameter values.

// Path parameter examples
const request = buildRequest({
  spec: openApiSpec,
  operationId: "getUserPosts", // GET /users/{userId}/posts/{postId}
  parameters: {
    userId: "123",
    postId: "456"
  }
});
// Results in: /users/123/posts/456

// Path parameter encoding
const request = buildRequest({
  spec: openApiSpec,
  operationId: "getFileByPath", // GET /files/{filePath}
  parameters: {
    filePath: "documents/my file.pdf"
  }
});
// Results in: /files/documents%2Fmy%20file.pdf

Query Parameters

Build query strings from parameter objects with proper encoding.

// Simple query parameters
const request = buildRequest({
  spec: openApiSpec,
  operationId: "searchUsers",
  parameters: {
    q: "john doe",
    limit: 10,
    offset: 20,
    active: true
  }
});
// Results in: ?q=john%20doe&limit=10&offset=20&active=true

// Array query parameters (OpenAPI 3.x style serialization)
const request = buildRequest({
  spec: openApiSpec,
  operationId: "getItems",
  parameters: {
    tags: ["javascript", "tutorial"],
    categories: [1, 2, 3]
  }
});
// Results in: ?tags=javascript&tags=tutorial&categories=1&categories=2&categories=3

// Object query parameters (exploded)
const request = buildRequest({
  spec: openApiSpec,
  operationId: "searchWithFilters",
  parameters: {
    filters: {
      type: "article",
      status: "published",
      year: 2023
    }
  }
});
// Results in: ?type=article&status=published&year=2023

Header Parameters

Add custom headers from parameter definitions.

// Header parameters
const request = buildRequest({
  spec: openApiSpec,
  operationId: "getLocalized",
  parameters: {
    "Accept-Language": "en-US,en;q=0.9",
    "X-Client-Version": "1.2.3",
    "If-None-Match": '"etag-value"'
  }
});
console.log(request.headers["Accept-Language"]); // en-US,en;q=0.9
console.log(request.headers["X-Client-Version"]); // 1.2.3

// Header parameter encoding
const request = buildRequest({
  spec: openApiSpec,
  operationId: "searchWithHeader",
  parameters: {
    "X-Search-Query": "complex query with spaces & symbols"
  }
});
// Header value is properly encoded

Cookie Parameters (OpenAPI 3.x)

Handle cookie parameters in OpenAPI 3.x specifications.

// Cookie parameters
const request = buildRequest({
  spec: openApi3Spec,
  operationId: "getPreferences",
  parameters: {
    sessionId: "abc123",
    theme: "dark",
    locale: "en-US"
  }
});
console.log(request.headers.Cookie); // sessionId=abc123; theme=dark; locale=en-US

Request Body (OpenAPI 3.x)

Handle request bodies with content type negotiation.

// JSON request body
const request = buildRequest({
  spec: openApi3Spec,
  operationId: "createUser",
  parameters: {
    body: {
      name: "John Doe",
      email: "john@example.com",
      age: 30
    }
  }
});
console.log(request.headers["Content-Type"]); // application/json
console.log(JSON.parse(request.body)); // { name: "John Doe", ... }

// Form data request body
const request = buildRequest({
  spec: openApi3Spec,
  operationId: "uploadProfile",
  parameters: {
    body: {
      avatar: fileObject,
      description: "Profile picture"
    }
  }
});
console.log(request.headers["Content-Type"]); // multipart/form-data; boundary=...
console.log(request.body instanceof FormData); // true

// Text request body
const request = buildRequest({
  spec: openApi3Spec,
  operationId: "updateDescription",
  parameters: {
    body: "This is a plain text description"
  }
});
console.log(request.headers["Content-Type"]); // text/plain

Form Data Parameters (Swagger 2.0)

Handle form data parameters in Swagger 2.0 specifications.

// Form data parameters
const request = buildRequest({
  spec: swagger2Spec,
  operationId: "uploadFile",
  parameters: {
    file: fileObject,
    description: "Document upload",
    category: "legal"
  }
});
console.log(request.body instanceof FormData); // true

// URL-encoded form data
const request = buildRequest({
  spec: swagger2Spec,
  operationId: "submitForm",
  parameters: {
    name: "John Doe",
    email: "john@example.com",
    subscribe: true
  }
});
console.log(request.headers["Content-Type"]); // application/x-www-form-urlencoded
console.log(request.body); // name=John%20Doe&email=john%40example.com&subscribe=true

Base URL Resolution

Compute base URLs for different OpenAPI versions and configurations.

/**
 * Compute base URL for operation
 * @param options - Base URL computation options
 * @returns Computed base URL
 */
function baseUrl(options: BaseUrlOptions): string;

interface BaseUrlOptions {
  /** OpenAPI specification */
  spec: object;
  /** Context URL for resolution */
  contextUrl?: string;
  /** URL scheme override (Swagger 2.0) */
  scheme?: string;
  /** Server URL override (OpenAPI 3.x) */
  server?: string;
  /** Server variables (OpenAPI 3.x) */
  serverVariables?: Record<string, string>;
  /** Path name for server selection */
  pathName?: string;
  /** HTTP method for server selection */
  method?: string;
  /** Server variable encoder */
  serverVariableEncoder?: (value: string) => string;
}

Base URL Examples:

// Swagger 2.0 base URL
const baseURL = baseUrl({
  spec: {
    host: "api.example.com",
    basePath: "/v1",
    schemes: ["https"]
  }
});
console.log(baseURL); // https://api.example.com/v1

// OpenAPI 3.x base URL
const baseURL = baseUrl({
  spec: {
    servers: [
      { url: "https://api.example.com/v1" },
      { url: "https://staging-api.example.com/v1" }
    ]
  }
});
console.log(baseURL); // https://api.example.com/v1

// OpenAPI 3.x with server variables
const baseURL = baseUrl({
  spec: {
    servers: [
      { 
        url: "https://{environment}.example.com/{version}",
        variables: {
          environment: { default: "api" },
          version: { default: "v1" }
        }
      }
    ]
  },
  serverVariables: {
    environment: "staging",
    version: "v2"
  }
});
console.log(baseURL); // https://staging.example.com/v2

Security Application

Apply security requirements to requests.

interface SecurityRequirements {
  authorized?: SecurityAuthorizations;
}

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

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

Security Examples:

// API Key in header
const request = buildRequest({
  spec: openApiSpec,
  operationId: "getProtectedData",
  securities: {
    authorized: {
      ApiKeyAuth: { value: "your-api-key" }
    }
  }
});
console.log(request.headers["X-API-Key"]); // your-api-key

// Bearer token
const request = buildRequest({
  spec: openApiSpec,
  operationId: "getProtectedData",
  securities: {
    authorized: {
      BearerAuth: { value: "jwt-token-here" }
    }
  }
});
console.log(request.headers.Authorization); // Bearer jwt-token-here

// Basic authentication
const request = buildRequest({
  spec: openApiSpec,
  operationId: "getProtectedData",
  securities: {
    authorized: {
      BasicAuth: {
        username: "user",
        password: "password"
      }
    }
  }
});
console.log(request.headers.Authorization); // Basic dXNlcjpwYXNzd29yZA==

Parameter Validation

Handle parameter validation and default values.

// Required parameter validation
try {
  const request = buildRequest({
    spec: openApiSpec,
    operationId: "getUserById",
    parameters: {} // Missing required userId parameter
  });
} catch (error) {
  console.error(error.message); // "Required parameter userId is not provided"
}

// Default parameter values
const request = buildRequest({
  spec: openApiSpec,
  operationId: "searchUsers",
  parameters: {
    q: "john"
    // limit parameter has default value of 10 in spec
  }
});
console.log(request.url); // includes limit=10 from default value

// Parameter type coercion (OpenAPI 3.x)
const request = buildRequest({
  spec: openApi3Spec,
  operationId: "getItems",
  parameters: {
    filters: '{"type": "article", "status": "published"}' // JSON string
  }
});
// String is parsed to object based on parameter schema

Common Types

interface ParameterObject {
  name: string;
  in: "query" | "header" | "path" | "cookie" | "body" | "formData";
  required?: boolean;
  schema?: SchemaObject;
  style?: string;
  explode?: boolean;
  allowEmptyValue?: boolean;
  default?: any;
}

interface OperationObject {
  operationId?: string;
  parameters?: ParameterObject[];
  requestBody?: RequestBodyObject;
  security?: SecurityRequirement[];
  servers?: ServerObject[];
}

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

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

interface HttpClient {
  (url: string, options?: HttpOptions): Promise<ResponseObject>;
  withCredentials?: boolean;
}

interface FetchFunction {
  (url: string, options?: RequestInit): Promise<Response>;
}

Install with Tessl CLI