@apidevtools/swagger-parser

What is @apidevtools/swagger-parser?

The @apidevtools/swagger-parser npm package is a tool that allows you to parse, validate, and dereference Swagger files (now known as OpenAPI Specifications). It supports Swagger 2.0 and OpenAPI 3.0, providing a way to ensure that API documentation is correct and adheres to the specification standards.

What are @apidevtools/swagger-parser's main functionalities?

Parse and Validate

This feature allows you to parse and validate a Swagger/OpenAPI file, ensuring it is correct and follows the specification.

const SwaggerParser = require('@apidevtools/swagger-parser');

SwaggerParser.validate('path/to/swagger.yaml')
  .then(api => {
    console.log('API name: %s, Version: %s', api.info.title, api.info.version);
  })
  .catch(err => {
    console.error(err);
  });

Dereference

Dereferencing resolves all $ref pointers in the Swagger/OpenAPI document, replacing them with their referenced objects or values.

const SwaggerParser = require('@apidevtools/swagger-parser');

SwaggerParser.dereference('path/to/swagger.yaml')
  .then(api => {
    console.log('Dereferenced API:', api);
  })
  .catch(err => {
    console.error(err);
  });

Bundle

Bundling takes all the separate files that make up a Swagger/OpenAPI document and bundles them into a single file.

const SwaggerParser = require('@apidevtools/swagger-parser');

SwaggerParser.bundle('path/to/swagger.yaml')
  .then(api => {
    console.log('Bundled API:', api);
  })
  .catch(err => {
    console.error(err);
  });

Other packages similar to @apidevtools/swagger-parser

swagger-jsdoc

This package generates swagger doc based on JSDoc comments. Unlike @apidevtools/swagger-parser, it is more focused on creating the swagger documentation from code rather than parsing and validating existing swagger files.

swagger-ui-express

This package allows you to serve auto-generated swagger-ui generated API docs from express, based on a swagger.json file. It is complementary to @apidevtools/swagger-parser, which can be used to validate and parse the swagger.json file before serving it with swagger-ui-express.

openapi-validator

This is an IBM package that validates OpenAPI specifications against the OpenAPI 3.0 or 2.0 specifications. It is similar to @apidevtools/swagger-parser in that it validates OpenAPI documents, but it is maintained by IBM and may have different validation features or standards.

README

Swagger 2.0 and OpenAPI 3.0 parser/validator

Features

• Parses Swagger specs in JSON or YAML format
• Validates against the Swagger 2.0 schema or OpenAPI 3.0 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, Instagram, 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

Related Projects

• Swagger CLI
• Swagger Express Middleware

Example

SwaggerParser.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 SwaggerParser.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 @apidevtools/swagger-parser

Usage

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

const SwaggerParser = require("@apidevtools/swagger-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 SwaggerParser from "@apidevtools/swagger-parser";

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

Contributing

I welcome any contributions, enhancements, and bug-fixes. File an issue on GitHub and submit a pull request.

Building/Testing

To build/test the project locally on your computer:

1. Clone this repo
   git clone https://github.com/APIDevTools/swagger-parser.git

2. Install dependencies
   npm install

3. Run the build script
   npm run build

4. Run the tests
   npm test

License

Swagger Parser is 100% free and open-source, under the MIT license. Use it however you want.

Big Thanks To

Thanks to these awesome companies for their support of Open Source developers ❤