or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

bundling.md dereferencing.md index.md parsing.md resolution.md validation.md

tile.json

API Bundling

Bundles multiple OpenAPI/Swagger files into a single specification containing only internal $ref pointers. This eliminates external file dependencies while preserving JSON references for smaller file sizes and circular reference safety.

Capabilities

Bundle Function

Creates a bundled OpenAPI specification with all external references converted to internal ones.

/**
 * Bundles all referenced files/URLs into a single API definition with internal $ref pointers
 * @param path - File path or URL of the OpenAPI definition (optional if api provided)
 * @param api - OpenAPI definition object to bundle instead of reading from path
 * @param options - Bundling options (optional)
 * @param callback - Error-first callback (optional, returns Promise if omitted)
 * @returns Promise resolving to the bundled OpenAPI definition
 */
function bundle(
  path?: string,
  api?: OpenAPI.Document,
  options?: SwaggerParser.Options,
  callback?: SwaggerParser.ApiCallback
): Promise<OpenAPI.Document>;

Instance Bundle Method

Bundle method available on SwaggerParser instances.

/**
 * Instance method for bundling OpenAPI specifications
 * @param path - File path or URL of the OpenAPI definition
 * @param api - OpenAPI definition object to bundle instead of reading from path
 * @param options - Bundling options
 * @param callback - Error-first callback
 * @returns Promise resolving to the bundled OpenAPI definition
 */
public bundle(
  path?: string,
  api?: OpenAPI.Document,
  options?: SwaggerParser.Options,
  callback?: SwaggerParser.ApiCallback
): Promise<OpenAPI.Document>;

Usage Examples:

import SwaggerParser from "@apidevtools/swagger-parser";

// Basic bundling
const bundledApi = await SwaggerParser.bundle("./petstore.yaml");

// Bundle is safe for JSON serialization
const jsonString = JSON.stringify(bundledApi, null, 2);

// Bundle from URL
const bundledApi = await SwaggerParser.bundle("https://api.example.com/openapi.yaml");

// Bundle with options
const bundledApi = await SwaggerParser.bundle("./api.yaml", {
  resolve: {
    http: false,  // Don't resolve HTTP references
    file: true    // Only bundle local file references
  }
});

// Using callback style
SwaggerParser.bundle("./api.yaml", (err, api) => {
  if (err) {
    console.error("Bundling failed:", err);
  } else {
    console.log("Bundled API size:", JSON.stringify(api).length);
  }
});

// Using instance
const parser = new SwaggerParser();
const bundledApi = await parser.bundle("./api.yaml");

// Access bundled content
console.log("Info:", bundledApi.info);
console.log("Definitions:", bundledApi.definitions); // Swagger 2.0
console.log("Components:", bundledApi.components);   // OpenAPI 3.x

Bundling Process

Before Bundling

# main.yaml
openapi: 3.0.0
info:
  title: My API
components:
  schemas:
    User:
      $ref: "./schemas/User.yaml"
    Error:
      $ref: "https://common.example.com/Error.yaml"

# schemas/User.yaml
type: object
properties:
  id:
    type: integer
  name:
    type: string

After Bundling

openapi: 3.0.0
info:
  title: My API
components:
  schemas:
    User:
      $ref: "#/components/schemas/~1schemas~1User.yaml"
    Error:
      $ref: "#/components/schemas/~1common.example.com~1Error.yaml"
    "~1schemas~1User.yaml":
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
    "~1common.example.com~1Error.yaml":
      type: object
      properties:
        message:
          type: string

Benefits of Bundling

Eliminates External Dependencies

All external file references become internal
API definition becomes self-contained
Reduces deployment complexity

Safe JSON Serialization

No circular references in the bundled result
Safe to use with JSON.stringify()
Maintains reference relationships

Smaller File Sizes

Preserves $ref pointers for repeated schemas
Avoids duplication of common definitions
More efficient than full dereferencing

Bundling Options

Bundling inherits all resolution options:

const bundledApi = await SwaggerParser.bundle("./api.yaml", {
  resolve: {
    file: true,           // Bundle local file references
    http: true,           // Bundle HTTP URL references
    external: true,       // Bundle external references
    http: {
      timeout: 5000,      // HTTP timeout
      headers: {          // Custom headers
        "Authorization": "Bearer token"
      }
    }
  }
});

Circular Reference Handling

Bundling safely handles circular references:

// API with circular references
const bundledApi = await SwaggerParser.bundle("./circular-api.yaml");

// Result is still JSON-serializable
const json = JSON.stringify(bundledApi); // No circular structure errors

// References are preserved
console.log(bundledApi.components.schemas.User.$ref); 
// "#/components/schemas/Profile"
console.log(bundledApi.components.schemas.Profile.$ref); 
// "#/components/schemas/User"

Working with Bundled APIs

const bundledApi = await SwaggerParser.bundle("./api.yaml");

// Access original content
console.log(bundledApi.info.title);
console.log(bundledApi.paths["/users"]);

// Access bundled definitions (Swagger 2.0)
if (bundledApi.definitions) {
  console.log("Bundled definitions:", Object.keys(bundledApi.definitions));
}

// Access bundled components (OpenAPI 3.x)
if (bundledApi.components && bundledApi.components.schemas) {
  console.log("Bundled schemas:", Object.keys(bundledApi.components.schemas));
}

// Save bundled API
const fs = require('fs');
fs.writeFileSync('./bundled-api.json', JSON.stringify(bundledApi, null, 2));

Error Handling

Bundling can fail during the resolution phase:

try {
  const bundledApi = await SwaggerParser.bundle("./api.yaml");
} catch (error) {
  // File resolution errors
  if (error.code === "ENOENT") {
    console.error("Referenced file not found:", error.path);
  }
  
  // HTTP resolution errors
  if (error.status) {
    console.error(`HTTP error: ${error.status} ${error.message}`);
  }
  
  // Parse errors in referenced files
  if (error instanceof SyntaxError) {
    console.error("Referenced file parse error:", error.message);
  }
}

Common Bundling Errors:

Referenced files not found
HTTP request failures for URL references
Parse errors in external files
Invalid $ref pointer syntax
Network connectivity issues