swagger-parser

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, 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

Related Projects
--------------------------
- Swagger CLI
- Swagger Express Middleware

Example
--------------------------

``javascript
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:

`javascript
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:

`bash
npm install @apidevtools/swagger-parser
`

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

`javascript
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:

`javascript
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. Open 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.

This package is Treeware. If you use it in production, then we ask that you buy the world a tree to thank us for our work. By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.

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