Skip to content

Latest commit

 

History

History
200 lines (134 loc) · 10.5 KB

swagger-parser.md

File metadata and controls

200 lines (134 loc) · 10.5 KB
Raw

SwaggerParser class

This is the default export of Swagger Parser. You can create instances of this class using new SwaggerParser(), or you can just call its static methods.

Properties
Methods

api

The api property is the parsed/bundled/dereferenced Swagger API object. This is the same value that is passed to the callback function (or Promise) when calling the parse, bundle, or dereference methods.

var parser = new SwaggerParser();

parser.api;  // => null

parser.dereference("my-api.yaml")
  .then(function(api) {
    typeof parser.api;     // => "object"

    api === parser.api; // => true
  });

$refs

The $refs property is a $Refs object, which lets you access all of the externally-referenced files in the API, as well as easily get and set specific values in the schema using JSON pointers.

This is the same value that is passed to the callback function (or Promise) when calling the resolve method.

var parser = new SwaggerParser();

parser.$refs.paths();           // => [] empty array

parser.dereference("my-api.json")
  .then(function() {
    parser.$refs.paths();       // => ["my-api.json"]
  });

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

  • api (required) - string or object
    A Swagger Object, or the file path or URL of your Swagger API. See the parse method for more info.

  • options (optional) - object
    See options for the full list of options

  • callback (optional) - function(err, api)
    A callback that will receive the dereferenced and validated Swagger object.

  • Return Value: Promise
    See Callbacks vs. Promises

Validates the Swagger API against the Swagger 2.0 schema or OpenAPI 3.0 Schema.

If the validate.spec option is enabled, then this method also validates against the Swagger 2.0 spec. The specification validator will catch some things that aren't covered by the Swagger 2.0 Schema, such as duplicate parameters, invalid MIME types, etc.

Note: Validating against the OpenAPI 3.0 Specification is not (yet) supported. For now, the validate.spec option is ignored if your API is in OpenAPI 3.0 format.

If validation fails, then an error will be passed to the callback function, or the Promise will reject. Either way, the error will contain information about why the API is invalid.

This method calls dereference internally, so the returned Swagger object is fully dereferenced.

SwaggerParser.validate("my-api.yaml")
  .then(function(api) {
    console.log('Yay! The API is valid.');
  })
  .catch(function(err) {
    console.error('Onoes! The API is invalid. ' + err.message);
  });

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

  • api (required) - string or object
    A Swagger Object, or the file path or URL of your Swagger API. See the parse method for more info.

  • options (optional) - object
    See options for the full list of options

  • callback (optional) - function(err, api)
    A callback that will receive the dereferenced Swagger object.

  • Return Value: Promise
    See Callbacks vs. Promises

Dereferences all $ref pointers in the Swagger API, replacing each reference with its resolved value. This results in a Swagger object that does not contain any $ref pointers. Instead, it's a normal JavaScript object tree that can easily be crawled and used just like any other JavaScript object. This is great for programmatic usage, especially when using tools that don't understand JSON references.

The dereference method maintains object reference equality, meaning that all $ref pointers that point to the same object will be replaced with references to the same object. Again, this is great for programmatic usage, but it does introduce the risk of circular references, so be careful if you intend to serialize the API using JSON.stringify(). Consider using the bundle method instead, which does not create circular references.

SwaggerParser.dereference("my-api.yaml")
  .then(function(api) {
    // The `api` object is a normal JavaScript object,
    // so you can easily access any part of the API using simple dot notation
    console.log(api.definitions.person.properties.firstName); // => {type: "string"}
  });

bundle(api, [options], [callback])

  • api (required) - string or object
    A Swagger Object, or the file path or URL of your Swagger API. See the parse method for more info.

  • options (optional) - object
    See options for the full list of options

  • callback (optional) - function(err, api)
    A callback that will receive the bundled Swagger object.

  • Return Value: Promise
    See Callbacks vs. Promises

Bundles all referenced files/URLs into a single api that only has internal $ref pointers. This lets you split-up your API however you want while you're building it, but easily combine all those files together when it's time to package or distribute the API to other people. The resulting API size will be small, since it will still contain internal JSON references rather than being fully-dereferenced.

This also eliminates the risk of circular references, so the API can be safely serialized using JSON.stringify().

SwaggerParser.bundle("my-api.yaml")
  .then(function(api) {
    console.log(api.definitions.person); // => {$ref: "#/definitions/schemas~1person.yaml"}
  });

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

  • api (required) - string or object
    A Swagger Object, or the file path or URL of your Swagger API.

    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.

  • options (optional) - object
    See options for the full list of options

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

  • Return Value: Promise
    See Callbacks vs. Promises

This method is used internally by other methods, such as bundle and dereference. You probably won't need to call this method yourself.

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

SwaggerParser.parse("my-api.yaml")
  .then(function(api) {
    console.log("API name: %s, Version: %s", api.info.title, api.info.version);
  });

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

  • api (required) - string or object
    A Swagger Object, or the file path or URL of your Swagger API. See the parse method for more info.

  • options (optional) - object
    See options for the full list of options

  • callback (optional) - function(err, $refs)
    A callback that will receive a $Refs object.

  • Return Value: Promise
    See Callbacks vs. Promises

This method is used internally by other methods, such as bundle and dereference. You probably won't need to call this method yourself.

Resolves all JSON references ($ref pointers) in the given Swagger API. 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 is a map of all the resolved references and their values.

SwaggerParser.resolve("my-api.yaml")
  .then(function($refs) {
    // $refs.paths() returns the paths of all the files in your API
    var filePaths = $refs.paths();

    // $refs.get() lets you query parts of your API
    var name = $refs.get("schemas/person.yaml#/properties/name");

    // $refs.set() lets you change parts of your API
    $refs.set("schemas/person.yaml#/properties/favoriteColor/default", "blue");
  });