Swagger-Parser

Parses, validates, and dereferences JSON/YAML Swagger specs in Node and browsers

|Live Demo! |------------------------------------------------------------

| !!! ALPHA NOTICE !!! |----------------------------------- |Swagger Parser 3.0 is in alpha. It is fairly stable, but not fully tested yet, so you may find bugs. Also, please be aware that the API might change slightly before final release.

To install the alpha, run npm install swagger-parser@alpha

Features

• Parses Swagger specs in JSON or YAML format
• Validates against the Swagger 2.0 schema and the Swagger 2.0 spec
• Resolves all $ref pointers, including pointers to external files and URLs
• Can dereference all $ref pointers, giving you a single JavaScript object that's easy to use
• You can choose to dereference only internal $refs, external $refs, or both
• Configurable caching of external files and URLs
• Tested in Node.js, io.js, Browserify, and all major web browsers on Windows, Mac, and Linux
• Tested on over 100 Google APIs
• Supports circular references, nested references, back-references, and cross-references
• Different $ref pointers to the same value are resolved to the same object instance, thus maintaining reference equality

Installation

Install using npm or bower, or just download swagger-parser.js or swagger-parser.min.js.

Node

npm install swagger-parser@alpha

Bower

bower install swagger-parser

Sample Usage

In Node or Browserify, you'll need to require("swagger-parser") first. On the web, either use <script src="dist/swagger-parser.js"></script> or add swagger-parser as a dependency in your AMD (Require.js) module.

// Use it with callbacks
SwaggerParser.parse("swagger.yaml", function(err, api) {
  if (err) {
    console.error(err);
  }
  else {
    console.log("API name: %s, Version: %s", api.info.title, api.info.version);
  }
});

// Or use it with Promises
SwaggerParser.parse("swagger.yaml")
  .then(function(api) {
    console.log("API name: %s, Version: %s", api.info.title, api.info.version);
  })
  .catch(function(err) {
    console.error(err);
  });

The API

• Class methods vs. Instance methods
• Callbacks vs. Promises
• Options
• Methods
  • parse()
  • resolve()
  • dereference()
  • validate()
• Properties
  • api
  • $refs

Class methods vs. Instance methods

All of SwaggerParser's methods are available as static (class) methods, or as instance methods. The static methods simply create a new SwaggerParser instance and then call the corresponding instance method. Thus, the following line...

SwaggerParser.resolve("MyApi.json");

... is the same as this:

var parser = new SwaggerParser();
parser.resolve("MyAPI.json");

The difference is that in the second example you now have a reference to parser, which means you can access the results (parser.api and parser.$refs) anytime you want, rather than just in the callback function. Another benefit of creating a SwaggerParser instance is to benefit from caching. SwaggerParser caches all of the files/URLs it downloads, so the next time you call parser.resolve(), it won't have to re-download those files again (as long as the cache hasn't expired).

Callbacks vs. Promises

Many people prefer ES6 Promise syntax instead of callbacks. SwaggerParser allows you to use whichever one you prefer. Every method accepts an optional callback and returns a Promise. So pick your poison.

Options

You can pass an options parameter to any method. You don't need to specify all options. Only the ones you want to change.

SwaggerParser.dereference("MyApi.yaml", {
    allow: {
        json: false,        // Don't allow JSON files
        yaml: true          // Allow YAML files
    }, 
    $refs: {
        internal: false     // Don't dereference internal $refs, only external
    },
    cache: {
        fs: 0,              // Don't cache local files
        http: 600           // Cache http URLs for 10 minutes
    },
    validate: {
        spec: false         // Allow the API to violate the Swagger spec
    }
});

parse(path, [options], [callback])

Parses the given Swagger file (in JSON or YAML format), and returns it as a JavaScript object. This method does not resolve $ref pointers, dereference anything, or validate your API. It simply parses one file and returns it.

• path (required) - string or object
  The file path or URL of your Swagger file. The path can be absolute or relative. In Node, the path is relative to process.cwd(). In the browser, it's relative to the URL of the page.
  
  If you already have the Swagger API as a JavaScript object, then you can pass that instead of a file path. Swagger Parser will verify that it's actually a Swagger Object.

• options (optional) - object
  See options above.

• callback (optional) - function(err, api)
  A callback that will receive the parsed Swagger Object, or an error.

• Return Value: Promise
  See Callbacks vs. Promises above.

resolve(path, [options], [callback])

Resolves $ref pointers in the given Swagger file. If it references any other files/URLs, then they will be downloaded and resolved as well (unless options.$refs.external is false). This method does not dereference anything. It simply gives you a $refs object, which has the resolved values for every $ref pointer.

• path (required) - string or object
  The file path or URL of your Swagger file. The path can be absolute or relative. In Node, the path is relative to process.cwd(). In the browser, it's relative to the URL of the page.
  
  If you already have the Swagger API as a JavaScript object, then you can pass that instead of a file path. Swagger Parser will crawl the object and resolve all of its $ref pointers.

• options (optional) - object
  See options above.

• callback (optional) - function(err, api)
  A callback that will receive a $refs object, which has the resolved values for every $ref pointer.

• Return Value: Promise
  See Callbacks vs. Promises above.

dereference(path, [options], [callback])

To-do

validate(path, [options], [callback])

To-do

api property

To-do

$refs property

To-do

Circular $Refs

Swagger files can contain circular $ref pointers, and Swagger-Parser will correctly parse them, resolve their values, and validate them against the Swagger schema. However, Swagger-Parser does not dereference circular references because this can easily cause stack overflows when the Swagger object is serialized, as well as other, more subtle bugs.

If your Swagger API includes circular references, then the callback will receive a ReferenceError to alert you that the Swagger object was not fully dereferenced. However, you can choose to ignore this error and use the api parameter anyway. All non-circular $ref pointers in the Swagger object will still be resolved and dereferenced like always. Circular $ref pointers will not be dereferenced, but they will be resolved, so you can access their resolved values in metadata.$refs.

person:
  properties:
    name:
      type: string
    spouse:
      type:
        $ref: person   # circular reference

Contributing

I welcome any contributions, enhancements, and bug-fixes. File an issue on GitHub and submit a pull request. Just make sure you build the code and run the unit tests first.

Building/Testing

To build the project locally on your computer:

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

2. Install dev dependencies
   npm install

3. Run the build script
   npm run build

4. Run unit tests
   npm test

License

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