Jsdoc documentation for functions

index.js

@@ -3,7 +3,22 @@
 const SchemaPack = require('./lib/schemapack.js').SchemaPack;
 
 module.exports = {
+  /**
+   * @description - Global callback type declaration
+   * @callback responseCallback
+   * @param {object} error - For handling error object
+   * @param {object} result - For handling conversion/validation object
+   */
+
   // Old API wrapping the new API
+
+  /**
+   * @description - Converts OpenAPI spec to a Postman collection
+   * @param {object} input - Contains OpenAPI spec specified in YAML/JSON
+   * @param {object} options - Holds user configurable properties like schemaFaker, requestNameSource, indentCharacter
+   * @param {responseCallback} cb - For return
+   * @returns {responseCallback} Callback with conversion results (success/failure)
+   */
   convert: function(input, options, cb) {
     var schema = new SchemaPack(input, options);
 
@@ -13,16 +28,31 @@ module.exports = {
     return cb(null, schema.validationResult);
   },
 
+  /**
+   * @description - Checks that input is valid YAML/JSON
+   * @param {object} input - Contains OpenAPI spec specified in YAML/JSON
+   * @returns {object} Object with success/failure status of schema validation along with its reason
+   */
   validate: function (input) {
     var schema = new SchemaPack(input);
     return schema.validationResult;
   },
 
+  /**
+   * @description - Checks JSON/YAML input in file hierarchy with a root dir
+   * @param {object} input - Contains OpenAPI spec specified in YAML/JSON
+   * @param {responseCallback} cb - For return
+   * @returns {responseCallback} Callback with success/failure status of schema validation along with its reason
+   */
   mergeAndValidate: function (input, cb) {
     var schema = new SchemaPack(input);
     schema.mergeAndValidate(cb);
   },
 
+  /**
+   * @description - Config options as kv-pairs passed to convert method
+   * @returns {object} Options object with configurable kv-pairs
+   */
   getOptions: function() {
     return SchemaPack.getOptions();
   },

lib/error.js

@@ -2,6 +2,7 @@
  * constructor openApiErr
  * @constructor
  * @param {*} message errorMessage
+ * @param {*} data - Error object
  */
 function openApiErr(message, data) {
   this.message = message || '';

lib/parse.js

@@ -5,6 +5,10 @@ var yaml = require('js-yaml'),
 
 module.exports = {
 
+  /** Converts json spec to JS object
+   * @param {String} spec OpenAPI input in string
+   * @returns {Object} JavaScript object from JSON OpenAPI input
+   */
   asJson: function (spec) {
     try {
       return JSON.parse(spec);
@@ -14,6 +18,10 @@ module.exports = {
     }
   },
 
+  /** Converts yaml spec to JS object
+   * @param {String} spec OpenAPI input in string
+   * @returns {Object} JavaScript object from YAML OpenAPI input
+   */
   asYaml: function (spec) {
     try {
       return yaml.safeLoad(spec);

lib/schemaUtils.js

@@ -95,7 +95,7 @@ schemaFaker.option({
 
 /**
  *
- * @param {*} input - input string that needs to be hashed
+ * @param {string} input - input string that needs to be hashed
  * @returns {*} sha1 hash of the string
  */
 function hash(input) {
@@ -325,6 +325,9 @@ module.exports = {
    * OperationParams take precedence over pathParams
    * @param {array} operationParam operation (Postman request)-level params.
    * @param {array} pathParam are path parent-level params.
+   * @param {object} components - components defined in the OAS spec. These are used to
+   * resolve references while generating params.
+   * @param {object} options - a standard list of options that's globally passed around. Check options.js for more.)
    * @returns {*} combined requestParams from operation and path params.
    */
   getRequestParams: function(operationParam, pathParam, components, options) {
@@ -379,6 +382,7 @@ module.exports = {
   /**
    * Generates a Trie-like folder structure from the root path object of the OpenAPI specification.
    * @param {Object} spec - specification in json format
+   * @param {object} options - a standard list of options that's globally passed around. Check options.js for more.)
    * @returns {Object} - The final object consists of the tree structure and collection variables
    */
   generateTrieFromPaths: function (spec, options) {
@@ -409,6 +413,11 @@ module.exports = {
       // returns a list of methods supported at each pathItem
       // some pathItem props are not methods
       // https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#pathItemObject
+
+      /**
+     * @param {Array} pathKeys - Keys in a path object
+     * @returns {Array} - Method names available for the path object
+     */
       getPathMethods = function(pathKeys) {
         var methods = [];
         // TODO: Show warning for incorrect schema if !pathKeys
@@ -522,8 +531,8 @@ module.exports = {
    * @param {object|array} commonPathVars - Object of path variables taken from the specification
    * @param {object} components - components defined in the OAS spec. These are used to
    * resolve references while generating params.
-  * @param {object} options - a standard list of options that's globally passed around. Check options.js for more.
-  * @param {object} schemaCache - object storing schemaFaker and schmeResolution caches
+   * @param {object} options - a standard list of options that's globally passed around. Check options.js for more.
+   * @param {object} schemaCache - object storing schemaFaker and schmeResolution caches
    * @returns {Array<object>} returns an array of sdk.Variable
    */
   convertPathVariables: function(type, providedPathVars, commonPathVars, components, options, schemaCache) {
@@ -804,6 +813,9 @@ module.exports = {
   /**
    * returns first example in the input map
    * @param {*} exampleObj map[string, exampleObject]
+   * @param {object} components - components defined in the OAS spec. These are used to
+   * resolve references while generating params.
+   * @param {object} options - a standard list of options that's globally passed around. Check options.js for more.)
    * @returns {*} first example in the input map type
    */
   getExampleData: function(exampleObj, components, options) {
@@ -832,16 +844,16 @@ module.exports = {
   },
 
   /**
-   * converts one of the eamples or schema in Media Type object to postman data
+   * converts one of the examples or schema in Media Type object to postman data
    * @param {*} bodyObj is MediaTypeObject
    * @param {*} requestType - Specifies whether the request body is of example request or root request
    * @param {*} contentType - content type header
    * @param {string} parameterSourceOption tells that the schema object is of request or response
    * @param {string} indentCharacter is needed for XML/JSON bodies only
    * @param {object} components - components defined in the OAS spec. These are used to
    * resolve references while generating params.
-  * @param {object} options - a standard list of options that's globally passed around. Check options.js for more.
-  * @param {object} schemaCache - object storing schemaFaker and schmeResolution caches
+   * @param {object} options - a standard list of options that's globally passed around. Check options.js for more.
+   * @param {object} schemaCache - object storing schemaFaker and schmeResolution caches
    * @returns {*} postman body data
    */
   // TODO: We also need to accept the content type
@@ -1377,6 +1389,7 @@ module.exports = {
   },
 
   /**
+   * converts operation item response to a Postman response
    * @param {*} response in operationItem responses
    * @param {*} code - response Code
    * @param {*} originalRequest - the request for the example
@@ -1453,6 +1466,9 @@ module.exports = {
 
   /**
    * @param {*} $ref reference object
+   * @param {object} components - components defined in the OAS spec. These are used to
+   * resolve references while generating params.
+   * @param {object} options - a standard list of options that's globally passed around. Check options.js for more.)
    * @returns {Object} reference object from the saved components
    * @no-unit-tests
    */
@@ -1750,6 +1766,12 @@ module.exports = {
   // along with the path object, this also returns the values of the
   // path variable's values
   // also, any endpoint-level params are merged into the returned pathItemObject
+  /**
+   * @param {*} method http method of a Postman transaction request object
+   * @param {*} url stringified url of a Postman transaction request object
+   * @param {*} schema takes an openapi schema object
+   * @returns {array} array of path objects
+   */
   findMatchingRequestFromSchema: function (method, url, schema) {
     // first step - get array of requests from schema
     let parsedUrl = require('url').parse(url),
@@ -1833,7 +1855,7 @@ module.exports = {
       );
 
       retVal.push({
-        // using path instead of operationId / sumamry since it's widely understood
+        // using path instead of operationId / summary since it's widely understood
         name: method + ' ' + path,
         path: matchedPath,
         jsonPath: matchedPathJsonPath + '.' + method.toLowerCase(),
@@ -1849,7 +1871,8 @@ module.exports = {
   },
 
   /**
-   *
+   * @description - validates value of the specified property against the schema passed in arguments
+   *  and returns array of mismatches (containing property, paths & reason)
    * @param {*} property - one of QUERYPARAM, PATHVARIABLE, HEADER, REQUEST_BODY, RESPONSE_HEADER, RESPONSE_BODY
    * @param {*} jsonPathPrefix - this will be prepended to all JSON schema paths on the request
    * @param {*} txnParamName - Optional - The name of the param being validated (useful for query params,
@@ -1984,6 +2007,7 @@ module.exports = {
 
   /**
    *
+   * @description - validates path variables of request schema (from Postman) and returns mismatches
    * @param {*} determinedPathVariables the key/determined-value pairs of the path variables (from Postman)
    * @param {*} transactionPathPrefix the jsonpath for this validation (will be prepended to all identified mismatches)
    * @param {*} schemaPath the applicable pathItem defined at the schema level
@@ -2078,6 +2102,17 @@ module.exports = {
     });
   },
 
+  /**
+   * @description - validates query params of a Postman request object and returns mismatches
+   * @param {*} requestUrl stringified url of a Postman transaction request object
+   * @param {*} transactionPathPrefix the jsonpath for this validation (will be prepended to all identified mismatches)
+   * @param {*} schemaPath the applicable pathItem defined at the schema level
+   * @param {*} components the components + paths from the OAS spec that need to be used to resolve $refs
+   * @param {*} options OAS options
+   * @param {*} schemaResolutionCache cache used to store resolved schemas
+   * @param {*} callback Callback
+   * @returns {array} mismatches (in the callback)
+   */
   checkQueryParams(requestUrl, transactionPathPrefix, schemaPath, components, options,
     schemaResolutionCache, callback) {
     let parsedUrl = require('url').parse(requestUrl),
@@ -2173,6 +2208,17 @@ module.exports = {
     });
   },
 
+  /**
+   * @description - validates headers in headers of a Postman request object and returns mismatches
+   * @param {*} headers headers for a Postman transaction request object
+   * @param {*} transactionPathPrefix the jsonpath for this validation (will be prepended to all identified mismatches)
+   * @param {*} schemaPath the applicable pathItem defined at the schema level
+   * @param {*} components the components + paths from the OAS spec that need to be used to resolve $refs
+   * @param {*} options OAS options
+   * @param {*} schemaResolutionCache cache used to store resolved schemas
+   * @param {*} callback Callback
+   * @returns {array} mismatches (in the callback)
+   */
   checkRequestHeaders: function (headers, transactionPathPrefix, schemaPath, components, options,
     schemaResolutionCache, callback) {
     let schemaHeaders = _.filter(schemaPath.parameters, (param) => { return param.in === 'header'; }),
@@ -2234,6 +2280,18 @@ module.exports = {
     });
   },
 
+  /**
+   * @description - validates response headers of a schema response and returns mismatches
+   * @param {*} schemaResponse response against a schema (extracted from schemaPath)
+   * @param {*} headers headers for a response in set of responses for Postman transaction request
+   * @param {*} transactionPathPrefix the jsonpath for this validation
+   * @param {*} schemaPathPrefix prepended to all JSON schema paths on the schema
+   * @param {*} components the components + paths from the OAS spec that need to be used to resolve $refs
+   * @param {*} options OAS options
+   * @param {*} schemaResolutionCache cache used to store resolved schemas
+   * @param {*} callback Callback
+   * @returns {array} mismatches (in the callback)
+   */
   checkResponseHeaders: function (schemaResponse, headers, transactionPathPrefix, schemaPathPrefix,
     components, options, schemaResolutionCache, callback) {
     // 0. Need to find relevant response from schemaPath.responses
@@ -2308,6 +2366,18 @@ module.exports = {
   },
 
   // Only application/json is validated for now
+  /**
+   * @description - validates body of a Postman request object and returns mismatches
+   * @param {*} requestBody body of a Postman transaction request object
+   * @param {*} transactionPathPrefix the jsonpath for this validation (will be prepended to all identified mismatches)
+   * @param {*} schemaPathPrefix prepended to all JSON schema paths on the schema
+   * @param {*} schemaPath the applicable pathItem defined at the schema level
+   * @param {*} components the components + paths from the OAS spec that need to be used to resolve $refs
+   * @param {*} options OAS options
+   * @param {*} schemaResolutionCache cache used to store resolved schemas
+   * @param {*} callback Callback
+   * @returns {array} mismatches (in the callback)
+   */
   checkRequestBody: function (requestBody, transactionPathPrefix, schemaPathPrefix, schemaPath,
     components, options, schemaResolutionCache, callback) {
     // check for body modes
@@ -2363,6 +2433,18 @@ module.exports = {
     return callback(null, []);
   },
 
+  /**
+   * @description - validates response of a schema and returns mismatches
+   * @param {*} schemaResponse response against a schema (extracted from schemaPath)
+   * @param {*} body response body in a set of responses for Postman transaction request
+   * @param {*} transactionPathPrefix the jsonpath for this validation
+   * @param {*} schemaPathPrefix prepended to all JSON schema paths on the schema
+   * @param {*} components the components + paths from the OAS spec that need to be used to resolve $refs
+   * @param {*} options OAS options
+   * @param {*} schemaResolutionCache cache used to store resolved schemas
+   * @param {*} callback Callback
+   * @returns {array} mismatches (in the callback)
+   */
   checkResponseBody: function (schemaResponse, body, transactionPathPrefix, schemaPathPrefix,
     components, options, schemaResolutionCache, callback) {
     let schemaContent = _.get(schemaResponse, ['content', 'application/json', 'schema']),
@@ -2400,6 +2482,18 @@ module.exports = {
     }, 0);
   },
 
+  /**
+   * @description - validates responses of a Postman request object and returns mismatches
+   * @param {*} responses set of responses for a Postman transaction request
+   * @param {*} transactionPathPrefix the jsonpath for this validation
+   * @param {*} schemaPathPrefix prepended to all JSON schema paths on the schema
+   * @param {*} schemaPath the applicable pathItem defined at the schema level
+   * @param {*} components the components + paths from the OAS spec that need to be used to resolve $refs
+   * @param {*} options OAS options
+   * @param {*} schemaResolutionCache cache used to store resolved schemas
+   * @param {*} cb Callback
+   * @returns {array} mismatches (in the callback)
+   */
   checkResponses: function (responses, transactionPathPrefix, schemaPathPrefix, schemaPath,
     components, options, schemaResolutionCache, cb) {
     // responses is an array of repsonses recd. for one Postman request
@@ -2450,6 +2544,8 @@ module.exports = {
   },
 
   /**
+   * @description - Determines whether path to a postman transaction request object & the schema path match.
+   * If they do, method calculates a similarity score
    * @param {string} postmanPath - parsed path (exclude host and params) from the Postman request
    * @param {string} schemaPath - schema path from the OAS spec (exclude servers object)
    * @returns {*} score + match + pathVars - higher score - better match. null - no match
@@ -2499,8 +2595,8 @@ module.exports = {
   },
 
   /**
-   * @param {*} pmSuffix
-   * @param {*} schemaPath
+   * @param {array} pmSuffix - Array of '/' separated path segments from schema path from OAS spec
+   * @param {array} schemaPath - Array of all possible suffixes of parsed path from Postman request
    * @returns {*} score - null of no match, int for match. higher value indicates better match
    * You get points for the number of URL segments that match
    * You are penalized for the number of schemaPath segments that you skipped