swagger-parser - npm Package Compare versions

Comparing version 2.1.0 to 2.1.1

lib/index.js

 (function() {
-  'use strict';
+    'use strict';
 
-  /**
-   * @name parser
-   * @type {{parse: function, defaults: defaults}}
-   */
-  module.exports = {
-    parse: require('./parse'),
-    defaults: require('./defaults')
-  };
+    /**
+     * @name parser
+     * @type {{parse: function, defaults: defaults}}
+     */
+    module.exports = {
+        parse: require('./parse'),
+        defaults: require('./defaults')
+    };
 
 })();

lib/parse.js

@@ -23,12 +23,13 @@ 'use strict';
  *
- * @param {string} swaggerPath
- * the file path or URL of a YAML or JSON Swagger spec.
+ * @param {string|SwaggerObject} swagger
+ * The file path or URL of a YAML or JSON Swagger spec.
+ * Or an already-parsed Swagger API object, which will still be dereferenced and validated.
  *
  * @param {defaults} options
- * options to enable/disable certain features. This object will be merged with the {@link defaults} object.
+ * Options to enable/disable certain features. This object will be merged with the {@link defaults} object.
  *
  * @param {function} callback
- * the callback function that will be passed the parsed SwaggerObject
+ * The callback function that will be passed the parsed SwaggerObject
  */
-function parse(swaggerPath, options, callback) {
+function parse(swagger, options, callback) {
     // Shift args if necessary
@@ -40,4 +41,4 @@ if (_.isFunction(options)) {
 
-    if (_.isEmpty(swaggerPath) || !_.isString(swaggerPath)) {
-        throw new Error('No Swagger file path was specified');
+    if (_.isEmpty(swagger)) {
+        throw new Error('Expected a Swagger file or object');
     }
@@ -56,3 +57,3 @@
     // Parse, dereference, and validate
-    parseSwaggerFile(swaggerPath, state, function(err, api) {
+    parseSwaggerFile(swagger, state, function(err, api) {
         errBack(err) ||
@@ -87,3 +88,3 @@ resolve(api, state, function(err, api) {
             util.doCallback(callback,
-                util.newSyntaxError(err, 'Error in "%s"', swaggerPath),
+                util.newSyntaxError(err, 'Error in Swagger definition'),
                 null,
@@ -98,24 +99,27 @@ getMetadata(state));
 /**
- * Parses the given JSON or YAML file or URL.
- * @param   {string}    filePath        The absolute or relative file path
- * @param   {State}     state           The state for the current parse operation
- * @param   {function}  callback
+ * Parses the given JSON or YAML file/URL or Swagger object, and verifies that it's a supported Swagger API.
+ *
+ * @param   {string|SwaggerObject}  swagger     The absolute or relative file path, URL, or Swagger object.
+ * @param   {State}                 state       The state for the current parse operation
+ * @param   {function}              callback
  */
-function parseSwaggerFile(filePath, state, callback) {
-    // Resolve the file path or url, relative to the CWD
-    var cwd = util.cwd();
-    util.debug('Resolving Swagger file path "%s", relative to "%s"', filePath, cwd);
-    filePath = url.resolve(cwd, filePath);
-    util.debug('    Resolved to %s', filePath);
+function parseSwaggerFile(swagger, state, callback) {
+    if (_.isString(swagger)) {
+        // Open/download the file/URL
+        var pathOrUrl = resolveSwaggerPath(swagger, state);
+        read.fileOrUrl(pathOrUrl, state, verifyParsedAPI);
+    }
+    else {
+        // It's already a parsed object, but we still need to validate it
+        resolveSwaggerPath('', state);
+        verifyParsedAPI(null, _.cloneDeep(swagger));
+    }
 
-    // Update the state
-    state.swaggerPath = filePath;
-    state.baseDir = path.dirname(filePath) + '/';
-    util.debug('Swagger base directory: %s', state.baseDir);
-
-    // Parse the file
-    read.fileOrUrl(filePath, state, function(err, api) {
+    function verifyParsedAPI(err, api) {
         if (err) {
             util.doCallback(callback, err);
         }
+        else if (!(api.swagger && api.info && api.paths)) {
+            return util.doCallback(callback, util.newSyntaxError('The object is not a valid Swagger API definition'));
+        }
         else if (supportedSwaggerVersions.indexOf(api.swagger) === -1) {
@@ -130,3 +134,3 @@ return util.doCallback(callback, util.newSyntaxError(
         }
-    });
+    }
 }
@@ -136,3 +140,30 @@
 /**
+ * Resolves the given file path or URL to determine the Swagger base directory.
+ *
+ * @param   {string}    pathOrUrl       The absolute or relative file or URL
+ * @param   {State}     state           The state for the current parse operation
+ * @returns {string}                    The resolved absolute file path or URL
+ */
+function resolveSwaggerPath(pathOrUrl, state) {
+    // Coerce String objects to string primitives
+    pathOrUrl = pathOrUrl.toString();
+
+    // Resolve the file path or url, relative to the CWD
+    var cwd = util.cwd();
+    util.debug('Resolving Swagger path "%s", relative to "%s"', pathOrUrl, cwd);
+    pathOrUrl = url.resolve(cwd, pathOrUrl);
+    util.debug('    Resolved to %s', pathOrUrl);
+
+    // Update the state
+    state.swaggerPath = pathOrUrl;
+    state.baseDir = path.dirname(pathOrUrl) + '/';
+    util.debug('Swagger base directory: %s', state.baseDir);
+
+    return pathOrUrl;
+}
+
+
+/**
  * Validates the given Swagger API against the Swagger schema.
+ *
  * @param   {SwaggerObject} api         The absolute or relative file path
@@ -165,2 +196,3 @@ * @param   {State}         state       The state for the current parse operation
  * Returns the metadata for the current parse operation
+ *
  * @param   {State}     state           The state for the current parse operation
@@ -167,0 +199,0 @@ * @returns {State}

lib/util.js

@@ -21,4 +21,3 @@ 'use strict';
      *
-     * NOTE: This unwinds the call stack, which avoids stack overflows
-     *       that occur when crawling very complex Swagger APIs
+     * NOTE: This unwinds the call stack, which avoids stack overflows that can occur when crawling very complex Swagger APIs
      *
@@ -25,0 +24,0 @@ * @param {function} callback

package.json

 {
   "name": "swagger-parser",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "description": "Swagger JSON/YAML parser and validator for Node and browsers",
@@ -66,3 +66,3 @@ "keywords": [
     "mocha": "^2.0.1",
-    "nock": "^0.52.0",
+    "nock": "^0.56",
     "sinon": "^1.12.1",
@@ -69,0 +69,0 @@ "vinyl-buffer": "^1.0.0",

README.md

@@ -7,3 +7,3 @@ Swagger-Parser
 [![Dependencies](https://img.shields.io/david/bigstickcarpet/swagger-parser.svg)](https://david-dm.org/bigstickcarpet/swagger-parser)
-[![Code Climate Score](https://codeclimate.com/github/BigstickCarpet/swagger-parser/badges/gpa.svg)](https://codeclimate.com/github/BigstickCarpet/swagger-parser)
+[![Code Climate Score](https://img.shields.io/codeclimate/github/BigstickCarpet/swagger-parser.svg)](https://codeclimate.com/github/BigstickCarpet/swagger-parser)
 [![Codacy Score](http://img.shields.io/codacy/6d686f916836433b9c013379fbe1052c.svg)](https://www.codacy.com/public/jamesmessinger/swagger-parser)
@@ -82,4 +82,6 @@ [![Coverage Status](https://img.shields.io/coveralls/BigstickCarpet/swagger-parser.svg)](https://coveralls.io/r/BigstickCarpet/swagger-parser)
 
-* __swaggerPath__ (_required_) - `string`<br>
+* __swagger__ (_required_) - `string` or `object`<br>
 The file path or URL of your Swagger file.  Relative paths are allowed.  In Node, the path is relative to `process.cwd()`.  In the browser, it's relative to the URL of the page.
+<br><br>
+If you pass an object instead of a string, then the parsing step will be skipped, but the object will still be validated, resolved, and dereferenced just like normal.
 
@@ -113,3 +115,3 @@ * __options__ (_optional_) - `object`<br>
 |:----------|:-------------------|:----------
-|`baseDir`  |string              |The directory of the main Swagger file, which is the base directory used to resolve any external $ref pointers.
+|`baseDir`  |string              |The base directory used to resolve any external $ref pointers.  If you passed a file path/URL to the `parse` method, then the `baseDir` is the directory of that file.  If you passed an object, then `baseDir` is set to `process.cwd()` in Node, or the URL of the current page in browsers.
 |`files`    |array of strings    |The full paths of all files that were parsed. This only includes local files, _not_ URLs.  If `Parser.parse()` was called with a local file path, then it will be the first item in this array.
@@ -124,3 +126,3 @@ |`urls`     |array of [URL objects](http://nodejs.org/api/url.html#url_url)|The URLs that were parsed.  If `Parser.parse()` was called with a URL, then it will be the first item in this array.
 
-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`.
+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`](#metadata).
 
@@ -127,0 +129,0 @@ ````yaml

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

3057019

increased by0.19%

Lines of code

24756

increased by0.22%

Number of lines in readme file

144

increased by1.41%

No dependency changes