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
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:
-
Clone this repo
git clone https://github.com/APIDevTools/swagger-parser.git
-
Install dependencies
npm install
-
Run the build script
npm run build
-
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 ❤