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 Parsing

Basic parsing functionality that reads OpenAPI/Swagger files in JSON or YAML format and converts them to JavaScript objects. This method validates file format and version compatibility but does not resolve $ref pointers or perform comprehensive validation.

Capabilities

Parse Function

Parses OpenAPI/Swagger specification files and returns them as JavaScript objects.

/**
 * Parses the given OpenAPI/Swagger API file
 * @param path - File path or URL of the OpenAPI definition (optional if api provided)
 * @param api - OpenAPI definition object to parse instead of reading from path
 * @param options - Parsing options (optional)
 * @param callback - Error-first callback (optional, returns Promise if omitted)
 * @returns Promise resolving to the parsed OpenAPI definition
 */
function parse(
  path?: string,
  api?: OpenAPI.Document,
  options?: SwaggerParser.Options,
  callback?: SwaggerParser.ApiCallback
): Promise<OpenAPI.Document>;

Instance Parse Method

Parse method available on SwaggerParser instances.

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

Usage Examples:

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

// Parse from file path
const api = await SwaggerParser.parse("./petstore.yaml");

// Parse from URL
const api = await SwaggerParser.parse("https://api.example.com/openapi.json");

// Parse from object
const apiObject = { openapi: "3.0.0", info: { title: "My API", version: "1.0.0" } };
const api = await SwaggerParser.parse(apiObject);

// Parse with options
const api = await SwaggerParser.parse("./api.yaml", {
  resolve: {
    file: false, // Don't resolve file references
    http: true   // Allow HTTP references
  }
});

// Using callback style
SwaggerParser.parse("./api.yaml", (err, api) => {
  if (err) {
    console.error(err);
  } else {
    console.log("Parsed API:", api.info.title);
  }
});

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

Supported Formats

JSON: Standard JSON format files
YAML: YAML format files (most common for OpenAPI)
Mixed: References can mix JSON and YAML formats

Supported Versions

Swagger: 2.0
OpenAPI: 3.0.0, 3.0.1, 3.0.2, 3.0.3, 3.0.4, 3.1.0, 3.1.1

Error Handling

Parse method throws SyntaxError for:

Invalid JSON/YAML syntax
Unsupported OpenAPI/Swagger versions
Invalid version format (number instead of string)
Missing required OpenAPI properties (paths or webhooks for OpenAPI 3.1)

try {
  const api = await SwaggerParser.parse("./invalid-api.yaml");
} catch (error) {
  if (error instanceof SyntaxError) {
    console.error("Invalid API format:", error.message);
  }
}