Reference Resolution

/**
 * Resolves all JSON references ($ref pointers) in the OpenAPI definition
 * @param path - File path or URL of the OpenAPI definition (optional if api provided)
 * @param api - OpenAPI definition object to resolve instead of reading from path
 * @param options - Resolution options (optional)
 * @param callback - Error-first callback receiving $Refs object (optional, returns Promise if omitted)
 * @returns Promise resolving to a $Refs object containing all resolved references
 */
function resolve(
  path?: string,
  api?: OpenAPI.Document,
  options?: SwaggerParser.Options,
  callback?: SwaggerParser.$RefsCallback
): Promise<$Refs>;

/**
 * Instance method for resolving JSON references in OpenAPI specifications
 * @param path - File path or URL of the OpenAPI definition
 * @param api - OpenAPI definition object to resolve instead of reading from path
 * @param options - Resolution options
 * @param callback - Error-first callback receiving $Refs object
 * @returns Promise resolving to a $Refs object
 */
public resolve(
  path?: string,
  api?: OpenAPI.Document,
  options?: SwaggerParser.Options,
  callback?: SwaggerParser.$RefsCallback
): Promise<$Refs>;

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

// Basic resolution
const $refs = await SwaggerParser.resolve("./petstore.yaml");

// Access resolved references
console.log($refs.paths()); // Array of all file paths
console.log($refs.values()); // Map of all resolved values

// Get specific resolved value
const userSchema = $refs.get("./schemas/User.yaml#/User");

// Check if references are circular
if ($refs.circular) {
  console.log("API contains circular references");
}

// Resolution with options
const $refs = await SwaggerParser.resolve("./api.yaml", {
  resolve: {
    file: true,     // Resolve file:// URLs
    http: true,     // Resolve http:// and https:// URLs
    external: true  // Resolve external references
  }
});

// Using callback style
SwaggerParser.resolve("./api.yaml", (err, $refs) => {
  if (err) {
    console.error("Resolution failed:", err);
  } else {
    console.log("Resolved files:", $refs.paths());
  }
});

// Using instance
const parser = new SwaggerParser();
const $refs = await parser.resolve("./api.yaml");

interface $Refs {
  /** Check if the API contains circular references */
  readonly circular: boolean;
  
  /** Get array of all resolved file paths */
  paths(): string[];
  
  /** Get map of all resolved values keyed by their JSON Pointer paths */
  values(): Record<string, any>;
  
  /** Get the resolved value at the specified JSON Pointer path */
  get(path: string): any;
  
  /** Set a value at the specified JSON Pointer path */
  set(path: string, value: any): void;
  
  /** Check if a JSON Pointer path exists */
  exists(path: string): boolean;
  
  /** Get metadata about a resolved file */
  info(path: string): FileInfo;
}

interface FileInfo {
  /** The resolved file URL */
  url: string;
  /** The file extension */
  extension: string;
  /** The MIME type */
  mimeType: string;
  /** The raw file contents */
  data: any;
}

interface ResolverOptions {
  /** Resolve file:// URLs */
  file?: boolean;
  /** Resolve http:// and https:// URLs */
  http?: boolean;
  /** Resolve external references */
  external?: boolean;
  /** HTTP resolver options */
  http?: HTTPResolverOptions;
}

interface HTTPResolverOptions {
  /** HTTP headers to send with requests */
  headers?: Record<string, string>;
  /** Request timeout in milliseconds */
  timeout?: number;
  /** Maximum number of redirects to follow */
  redirects?: number;
}

# Reference to definition within same file
$ref: "#/definitions/User"
$ref: "#/components/schemas/User"

# Reference to another file
$ref: "./schemas/User.yaml"
$ref: "../common/Error.json"

# Reference to remote file
$ref: "https://api.example.com/schemas/User.yaml"
$ref: "http://localhost:3000/schemas/Error.json"

# Reference with JSON Pointer
$ref: "./definitions.yaml#/definitions/User"
$ref: "https://api.example.com/schemas.json#/components/schemas/Error"

const $refs = await SwaggerParser.resolve("./api.yaml");

if ($refs.circular) {
  console.log("API contains circular references");
  
  // Still safe to use - references are resolved but maintain structure
  const userSchema = $refs.get("#/components/schemas/User");
}

try {
  const $refs = await SwaggerParser.resolve("./api.yaml");
} catch (error) {
  // File not found
  if (error.code === "ENOENT") {
    console.error("File not found:", error.path);
  }
  
  // HTTP errors
  if (error.status) {
    console.error(`HTTP ${error.status}: ${error.message}`);
  }
  
  // Invalid JSON Pointer
  if (error.message.includes("JSON Pointer")) {
    console.error("Invalid reference:", error.message);
  }
}