Next Perpendicular Moonlanding

    @readme/openapi-parser
    TypeScript icon, indicating that this package has built-in type declarations

    2.2.0 • Public • Published

    Swagger 2.0 and OpenAPI 3.x parser/validator

    Build Status Tested on APIs.guru

    npm License

    OS and Browser Compatibility

    Online Demo

    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

    Install

    npm i @readme/openapi-parser

    DownloadsWeekly Downloads

    23,692

    Version

    2.2.0

    License

    MIT

    Unpacked Size

    76.9 kB

    Total Files

    11

    Last publish

    Collaborators

    • dannobytes
    • dok
    • gkoberger
    • domharrington
    • mjcuva
    • kanadgupta
    • jonursenbach
    • rafegoldberg
    • dashron
    • iliast