swagger-jsdoc - npm Package Compare versions

Comparing version 4.3.0 to 4.3.1

bin/swagger-jsdoc.js

 #!/usr/bin/env node
 
-/**
- * Module dependencies.
- */
 const program = require('commander');
@@ -13,5 +10,3 @@ const fs = require('fs');
 
-// Useful input.
 const input = process.argv.slice(2);
-// The spec, following a convention.
 let output = 'swagger.json';
@@ -21,3 +16,2 @@
  * Creates a swagger specification from a definition and a set of files.
- * @function
  * @param {object} swaggerDefinition - The swagger definition object.
@@ -28,14 +22,9 @@ * @param {array} apis - List of files to extract documentation from.
 function createSpecification(swaggerDefinition, apis, fileName) {
-  // Options for the swagger docs
+  let swaggerSpec;
+  const ext = path.extname(fileName);
   const options = {
-    // Import swaggerDefinitions
     swaggerDefinition,
-    // Path to the API docs
     apis,
   };
 
-  // Initialize swagger-jsdoc -> returns validated JSON or YAML swagger spec
-  let swaggerSpec;
-  const ext = path.extname(fileName);
-
   if (ext === '.yml' || ext === '.yaml') {
@@ -50,36 +39,30 @@ swaggerSpec = jsYaml.dump(swaggerJSDoc(options), {
 
-  fs.writeFile(fileName, swaggerSpec, (err) => {
-    if (err) {
-      throw err;
-    }
-    console.log('Swagger specification is ready.');
-  });
+  fs.writeFileSync(fileName, swaggerSpec);
+  console.log('Swagger specification is ready.');
 }
 
-function loadJsSpecification(data, resolvedPath) {
+/**
+ * Get an object of the definition file configuration.
+ * @param {string} defPath
+ * @param {object} swaggerDefinition
+ */
+function loadDefinition(defPath, swaggerDefinition) {
+  const resolvedPath = path.resolve(defPath);
+  const extName = path.extname(resolvedPath);
+
   // eslint-disable-next-line
-  return require(resolvedPath);
-}
+  const loadJs = () => require(resolvedPath);
+  const loadJson = () => JSON.parse(swaggerDefinition);
+  const loadYaml = () =>
+    jsYaml.load(swaggerDefinition, {
+      schema: jsYaml.JSON_SCHEMA, // OpenAPI spec mandates JSON-compatible YAML
+    });
 
-const YAML_OPTS = {
-  // OpenAPI spec mandates JSON-compatible YAML
-  schema: jsYaml.JSON_SCHEMA,
-};
+  const LOADERS = {
+    '.js': loadJs,
+    '.json': loadJson,
+    '.yml': loadYaml,
+    '.yaml': loadYaml,
+  };
 
-function loadYamlSpecification(data) {
-  return jsYaml.load(data, YAML_OPTS);
-}
-
-const LOADERS = {
-  '.js': loadJsSpecification,
-  '.json': JSON.parse,
-  '.yml': loadYamlSpecification,
-  '.yaml': loadYamlSpecification,
-};
-
-// Get an object of the definition file configuration.
-function loadSpecification(defPath, data) {
-  const resolvedPath = path.resolve(defPath);
-
-  const extName = path.extname(resolvedPath);
   const loader = LOADERS[extName];
@@ -92,4 +75,3 @@
 
-  const swaggerDefinition = loader(data, resolvedPath);
-  return swaggerDefinition;
+  return loader();
 }
@@ -133,3 +115,3 @@
   try {
-    swaggerDefinition = loadSpecification(program.definition, data);
+    swaggerDefinition = loadDefinition(program.definition, data);
   } catch (error) {
@@ -136,0 +118,0 @@ const message = `Error while loading definition file '${program.definition}':\n${error.message}`;

lib/helpers/convertGlobPaths.js

@@ -5,6 +5,4 @@ const glob = require('glob');
  * Converts an array of globs to full paths
- * @function
  * @param {array} globs - Array of globs and/or normal paths
  * @return {array} Array of fully-qualified paths
- * @requires glob
  */
@@ -11,0 +9,0 @@ function convertGlobPaths(globs) {

lib/helpers/createSpecification.js

@@ -6,3 +6,2 @@ /* eslint no-self-assign: 0 */
  * @see https://goo.gl/Eoagtl
- * @function
  * @param {object} definition - The `definition` or `swaggerDefinition` from options.
@@ -9,0 +8,0 @@ * @returns {object} Object containing required properties of a given specification version.

lib/helpers/filterJsDocComments.js

@@ -5,6 +5,4 @@ const jsYaml = require('js-yaml');
  * Filters JSDoc comments for those tagged with '@swagger'
- * @function
  * @param {array} jsDocComments - JSDoc comments
  * @returns {array} JSDoc comments tagged with '@swagger'
- * @requires js-yaml
  */
@@ -11,0 +9,0 @@ function filterJsDocComments(jsDocComments) {

lib/helpers/finalizeSpecificationObject.js

@@ -7,3 +7,2 @@ const parser = require('swagger-parser');
  * Solves validator error: "Schema error should NOT have additional properties"
- * @function
  * @param {object} inputSpec - The swagger/openapi specification
@@ -10,0 +9,0 @@ * @param {object} improvedSpec - The cleaned version of the inputSpec

lib/helpers/hasEmptyProperty.js

 /**
  * Checks if there is any properties of @obj that is a empty object
- * @function
  * @param {object} obj - the object to check
@@ -5,0 +4,0 @@ */

lib/helpers/parseApiFile.js

@@ -7,3 +7,2 @@ const fs = require('fs');
  * Parses the provided API file for JSDoc comments.
- * @function
  * @param {string} file - File to be parsed
@@ -10,0 +9,0 @@ * @returns {{jsdoc: array, yaml: array}} JSDoc comments and Yaml files

lib/helpers/parseApiFileContent.js

@@ -6,8 +6,5 @@ const doctrine = require('doctrine');
  * Parse the provided API file content.
- *
- * @function
  * @param {string} fileContent - Content of the file
  * @param {string} ext - File format ('.yaml', '.yml', '.js', etc.)
  * @returns {{jsdoc: array, yaml: array}} JSDoc comments and Yaml files
- * @requires doctrine
  */
@@ -14,0 +11,0 @@ function parseApiFileContent(fileContent, ext) {

lib/helpers/specification.js

@@ -7,3 +7,2 @@ /* eslint no-param-reassign: 0 */
  * The target, is the part of the swagger specification that holds all tags.
- * @function
  * @param {object} target - Swagger object place to include the tags data.
@@ -32,3 +31,2 @@ * @param {object} tag - Swagger tag object to be included.
  * Adds the tags property to a swagger object.
- * @function
  * @param {object} conf - Flexible configuration.
@@ -57,3 +55,2 @@ */
  * List of deprecated or wrong swagger schema properties in singular.
- * @function
  * @returns {array} The list of deprecated property names.
@@ -77,3 +74,2 @@ */
  * Makes a deprecated property plural if necessary.
- * @function
  * @param {string} propertyName - The swagger property name to check.
@@ -93,3 +89,2 @@ * @returns {string} The updated propertyName if neccessary.
  * Handles swagger propertyName in pathObject context for swaggerObject.
- * @function
  * @param {object} swaggerObject - The swagger object to update.
@@ -153,3 +148,2 @@ * @param {object} pathObject - The input context of an item for swaggerObject.
  * Adds the data in to the swagger object.
- * @function
  * @param {object} swaggerObject - Swagger object which will be written to
@@ -156,0 +150,0 @@ * @param {object[]} data - objects of parsed swagger data from yml or jsDoc

lib/index.js

@@ -1,26 +0,26 @@
-/** @module index */
-
+const { YAMLException } = require('js-yaml');
 const getSpecificationObject = require('./helpers/getSpecificationObject');
 
-const createSpecification = require('./helpers/createSpecification');
-const parseApiFileContent = require('./helpers/parseApiFileContent');
-const updateSpecificationObject = require('./helpers/updateSpecificationObject');
-const finalizeSpecificationObject = require('./helpers/finalizeSpecificationObject');
-
 /**
  * Generates the specification.
- * @function
  * @param {object} options - Configuration options
  * @returns {object} Output specification
- * @requires swagger-parser
  */
 module.exports = (options) => {
+  if (!options) {
+    throw new Error(`Missing or invalid input: 'options' is required`);
+  }
+
   if (!options.swaggerDefinition && !options.definition) {
     throw new Error(
-      'Provided swaggerDefinition or definition attributes are incorrect.'
+      `Missing or invalid input: 'options.swaggerDefinition' or 'options.definition' is required`
     );
-  } else if (!options.apis) {
-    throw new Error('Provided apis attribute are incorrect.');
   }
 
+  if (!options.apis || !Array.isArray(options.apis)) {
+    throw new Error(
+      `Missing or invalid input: 'options.apis' is required and it should be an array.`
+    );
+  }
+
   try {
@@ -31,19 +31,12 @@ const specificationObject = getSpecificationObject(options);
   } catch (err) {
-    let msg = err.message;
-    if (err.mark && err.mark.buffer && err.mark.line) {
-      const { line } = err.mark;
-      const bufferParts = err.mark.buffer.split('\n');
-      bufferParts[
-        line
-      ] = `${bufferParts[line]} -------------- Pay attention at this place`;
-      msg = bufferParts.join('\n');
+    if (err instanceof YAMLException) {
+      console.log('Error in yaml file:', err.mark.buffer);
     }
-    console.warn(msg);
-    throw new Error(err);
+    throw err;
   }
 };
 
-module.exports.createSpecification = createSpecification;
-module.exports.parseApiFileContent = parseApiFileContent;
-module.exports.updateSpecificationObject = updateSpecificationObject;
-module.exports.finalizeSpecificationObject = finalizeSpecificationObject;
+module.exports.createSpecification = require('./helpers/createSpecification');
+module.exports.parseApiFileContent = require('./helpers/parseApiFileContent');
+module.exports.updateSpecificationObject = require('./helpers/updateSpecificationObject');
+module.exports.finalizeSpecificationObject = require('./helpers/finalizeSpecificationObject');

package.json

 {
   "name": "swagger-jsdoc",
-  "version": "4.3.0",
+  "description": "Generates swagger doc based on JSDoc",
+  "version": "4.3.1",
   "engines": {
     "node": ">=10.0.0"
   },
-  "license": "MIT",
-  "description": "Generates swagger doc based on JSDoc",
-  "homepage": "https://github.com/Surnet/swagger-jsdoc",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/Surnet/swagger-jsdoc.git"
-  },
-  "keywords": [
-    "jsdoc",
-    "restful",
-    "api",
-    "express",
-    "swagger"
-  ],
-  "author": "https://github.com/Surnet/swagger-jsdoc/graphs/contributors",
-  "bugs": {
-    "url": "https://github.com/Surnet/swagger-jsdoc/issues"
-  },
-  "main": "index.js",
   "scripts": {
@@ -32,2 +14,3 @@ "test:lint": "eslint .",
   },
+  "main": "index.js",
   "bin": {
@@ -60,2 +43,19 @@ "swagger-jsdoc": "./bin/swagger-jsdoc.js"
   },
+  "license": "MIT",
+  "homepage": "https://github.com/Surnet/swagger-jsdoc",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Surnet/swagger-jsdoc.git"
+  },
+  "keywords": [
+    "jsdoc",
+    "restful",
+    "api",
+    "express",
+    "swagger"
+  ],
+  "author": "https://github.com/Surnet/swagger-jsdoc/graphs/contributors",
+  "bugs": {
+    "url": "https://github.com/Surnet/swagger-jsdoc/issues"
+  },
   "resolutions": {
@@ -62,0 +62,0 @@ "lodash": "^4.17.19",

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

Worsened metrics

Total package byte prevSize

28563

decreased by-3.1%

Number of package files

21

decreased by-4.55%

Lines of code

553

decreased by-7.06%

No dependency changes