@readme/openapi-parser

What is @readme/openapi-parser?

@readme/openapi-parser is an npm package designed to parse, validate, and dereference OpenAPI (formerly known as Swagger) definitions. It helps developers work with OpenAPI specifications by providing tools to ensure the correctness and completeness of API definitions.

What are @readme/openapi-parser's main functionalities?

Parsing OpenAPI Definitions

This feature allows you to parse an OpenAPI definition from a file. The parsed object can then be used for further processing or validation.

const OpenAPIParser = require('@readme/openapi-parser');

async function parseOpenAPIDefinition(filePath) {
  const api = await OpenAPIParser.parse(filePath);
  console.log(api);
}

parseOpenAPIDefinition('path/to/openapi.yaml');

Validating OpenAPI Definitions

This feature allows you to validate an OpenAPI definition. It checks for errors and inconsistencies in the API definition and throws an error if any issues are found.

const OpenAPIParser = require('@readme/openapi-parser');

async function validateOpenAPIDefinition(filePath) {
  try {
    const api = await OpenAPIParser.validate(filePath);
    console.log('API definition is valid:', api);
  } catch (err) {
    console.error('API definition is invalid:', err);
  }
}

validateOpenAPIDefinition('path/to/openapi.yaml');

Dereferencing OpenAPI Definitions

This feature allows you to dereference an OpenAPI definition. It resolves all $ref pointers in the API definition, replacing them with the actual referenced objects.

const OpenAPIParser = require('@readme/openapi-parser');

async function dereferenceOpenAPIDefinition(filePath) {
  const api = await OpenAPIParser.dereference(filePath);
  console.log(api);
}

dereferenceOpenAPIDefinition('path/to/openapi.yaml');

Other packages similar to @readme/openapi-parser

swagger-parser

swagger-parser is a popular npm package for parsing, validating, and dereferencing Swagger and OpenAPI definitions. It offers similar functionalities to @readme/openapi-parser but is more widely used and has a larger community.

openapi-schema-validator

openapi-schema-validator is a package focused on validating OpenAPI 3.0 schemas. While it does not offer parsing or dereferencing capabilities, it provides robust validation features for OpenAPI schemas.

openapi-types

openapi-types is a TypeScript library that provides type definitions for OpenAPI specifications. It is useful for TypeScript developers who want to ensure type safety when working with OpenAPI definitions, but it does not offer parsing or validation functionalities.

README

Swagger 2.0 and OpenAPI 3.x parser/validator

Features

• Parses Swagger specs in JSON or YAML format
• Validates against the Swagger 2.0 schema, OpenAPI 3.0 Schema, or OpenAPI 3.1 Schema
• Resolves all $ref pointers, including external files and URLs
• Can bundle all your Swagger files into a single file that only has internal $ref pointers
• Can dereference all $ref pointers, giving you a normal JavaScript object that's easy to work with
• Tested in Node.js and all modern web browsers on Mac, Windows, and Linux
• Tested on over 1,500 real-world APIs from Google, Microsoft, Facebook, Spotify, etc.
• Supports circular references, nested references, back-references, and cross-references
• Maintains object reference equality — $ref pointers to the same value always resolve to the same object instance

Example

OpenAPIParser.validate(myAPI, (err, api) => {
  if (err) {
    console.error(err);
  } else {
    console.log('API name: %s, Version: %s', api.info.title, api.info.version);
  }
});

Or use async/await or Promise syntax instead. The following example is the same as above:

try {
  let api = await OpenAPIParser.validate(myAPI);
  console.log('API name: %s, Version: %s', api.info.title, api.info.version);
} catch (err) {
  console.error(err);
}

For more detailed examples, please see the API Documentation

Installation

Install using npm:

npm install @readme/openapi-parser

Usage

When using Swagger Parser in Node.js apps, you'll probably want to use CommonJS syntax:

const OpenAPIParser = require('@readme/openapi-parser');

When using a transpiler such as Babel or TypeScript, or a bundler such as Webpack or Rollup, you can use ECMAScript modules syntax instead:

import OpenAPIParser from '@readme/openapi-parser';

Differences from @apidevtools/swagger-parser

@apidevtools/swagger-parser returns schema validation errors as the raw error stack from Ajv. For example:

To reduce the amount of potentially unnecessary noise that these JSON pointer errors provide, @readme/openapi-parser utilizes better-ajv-errors, along with some intelligent reduction logic, to only surface the errors that actually matter.

Additionally with these error reporting differences, this library ships with a validation.colorizeErrors option that will disable colorization within these prettified errors.

Browser support

Swagger Parser supports recent versions of every major web browser. Older browsers may require Babel and/or polyfills.

To use Swagger Parser in a browser, you'll need to use a bundling tool such as Webpack, Rollup, Parcel, or Browserify. Some bundlers may require a bit of configuration, such as setting browser: true in rollup-plugin-resolve.

API Documentation

Full API documentation is available right here