swagger-endpoint-validator - npm Package Compare versions

Comparing version 2.0.2 to 2.1.0

index.js

@@ -18,7 +18,2 @@ const debug = require('debug')('swagger-endpoint-validator');
  * @param {Object} options - Configuration object.
- * @param {boolean} [options.validateRequests=true] - true to validate the requests.
- * @param {boolean} [options.validateResponses=true] - true to validate the responses.
- * @param {string|boolean} [options.validateFormats='fast'] - specifies the strictness of validation of string formats (one of 'fast', 'full' or false).
- * @param {string} [options.validationEndpoint=null] - endpoint to do schemas validation agains the OpenAPI schema.
- * @param {string} [options.apiDocEndpoint=null] - endpoint to show UI based API documentation.
  * @param {string} options.format - format of the OpenAPI specification documentation.
@@ -29,2 +24,16 @@ * @param {Object} [options.yaml={}] - Extra configuration when format = 'yaml'.
  * @param {Object} [options.jsdoc={}] - Extra configuration when format = 'jsdoc'.
+ * @param {string} [options.validationEndpoint=null] - endpoint to do schemas validation agains the OpenAPI schema.
+ * @param {string} [options.apiDocEndpoint=null] - endpoint to show UI based API documentation.
+ * @param {*} [options.validateRequests=true] - Determines whether the validator should validate requests.
+ * @param {*} [options.validateResponses=true] - Determines whether the validator should validate responses. Also accepts response validation options.
+ * @param {*} [options.validateSecurity=true] -Determines whether the validator should validate securities e.g. apikey, basic, oauth2, openid, etc
+ * @param {*} [options.validateFormats='fast'] - Specifies the strictness of validation of string formats.
+ * @param {*} [options.unknownFormats=true] - Defines how the validator should behave if an unknown or custom format is encountered.
+ * @param {*} [options.operationHandlers=false] - Defines the base directory for operation handlers.
+ * @param {*} [options.ignorePaths=null] - Defines a regular expression that determines whether a path(s) should be ignored. Any path that matches the regular expression will be ignored by the validator.
+ * @param {*} [options.fileUploader=true] - Specifies the options to passthrough to multer. express-openapi-validator uses multer to handle file uploads.
+ * @param {*} [options.coerceTypes=true] - Determines whether the validator should coerce value types to match the type defined in the OpenAPI spec.
+ * @param {*} [options.$refParser.mode='bundle'] - Determines how JSON schema references are resolved.
+ *
+ * @see {@link https://www.npmjs.com/package/express-openapi-validator#advanced-usage|express-openapi-validator} for advanced configuration options.
  */
@@ -31,0 +40,0 @@ const init = async (app, options) => {

lib/errors.js

@@ -15,3 +15,2 @@ const util = require('util');
 
-
 module.exports = errorFactory;

lib/normalizeOptions.js

@@ -26,9 +26,8 @@ const debug = require('debug')('swagger-endpoint-validator:options');
 	const normalizedOptions = {
-		validateRequests: options.validateRequests !== undefined ? options.validateRequests : true,
-		validateResponses: options.validateResponses !== undefined ? options.validateResponses : true,
+		...options,
+		format: options.format || SUPPORTED_FORMATS.YAML,
+		[options.format]: formatOptions[selectedFormat],
 		validationEndpoint: options.validationEndpoint || null,
-		validateFormats: options.validateFormats !== undefined ? options.validateFormats : 'fast',
 		apiDocEndpoint: options.apiDocEndpoint || null,
-		format: options.format || SUPPORTED_FORMATS.YAML,
-		[options.format]: formatOptions[selectedFormat],
+		validateResponses: options.validateResponses !== undefined ? options.validateResponses : true,
 	};
@@ -35,0 +34,0 @@

lib/openAPISpecification.js

@@ -5,5 +5,4 @@ const debug = require('debug')('swagger-endpoint-validator:openapi-spec');
 const swaggerJSDoc = require('swagger-jsdoc');
-const expressSwaggerGenerator = require('express-swagger-generator');
+const expressJSDocSwagger = require('express-jsdoc-swagger');
 const Enforcer = require('openapi-enforcer');
-const apiConverter = require('swagger2openapi');
 
@@ -24,27 +23,9 @@ const { SUPPORTED_FORMATS } = require('./constants');
 		[SUPPORTED_FORMATS.JSDOC]: async formatOptions => {
-			// eslint-disable-next-line no-console
-			console.warn(
-				'\x1b[33m%s\x1b[0m',
-				'⚠️  \'jsdoc\' format will be deprecated in a future version of the library!.'
-				+ 'Please migrate your swagger documentation to \'yaml\' or \'yaml_jsdoc\' format',
-			);
+			const instance = expressJSDocSwagger(app)(formatOptions);
 
-			const doc = expressSwaggerGenerator(app)(formatOptions);
+			return new Promise((resolve, reject) => {
+				instance.on('finish', resolve);
 
-			debug('Converting specification from Swagger v2 to OpenAPI v3...');
-			// swagger2openapi does the conversion between OpenAPI 2.0 and OpenAPI 3.0, but it has a small error:
-			// It doesn't add 'type: object' to the definitions.
-			// So we'll do it manually until the issue is solved.
-			// see https://github.com/Mermade/oas-kit/issues/220
-			const definitions = {};
-			Object.assign(definitions, doc.definitions);
-			Object.keys(definitions).forEach(key => { definitions[key].type = 'object'; });
-			const modifiedDoc = {
-				...doc,
-				definitions,
-			};
-			const conversion = await apiConverter.convertObj(modifiedDoc, {});
-			debug('Specification converted to OpenAPI v3!');
-
-			return conversion.openapi;
+				instance.on('error', reject);
+			});
 		},
@@ -51,0 +32,0 @@ [SUPPORTED_FORMATS.YAML]: formatOptions => jsYaml.safeLoad(fs.readFileSync(formatOptions.file, 'utf-8')),

lib/validator.js

@@ -22,7 +22,27 @@ const debug = require('debug')('swagger-endpoint-validator:validator');
 
+	const {
+		$refParser,
+		coerceTypes,
+		fileUploader,
+		ignorePaths,
+		operationHandlers,
+		unknownFormats,
+		validateFormats,
+		validateRequests,
+		validateResponses,
+		validateSecurity,
+	} = options;
+
 	await new OpenApiValidator({
 		apiSpec: spec.doc,
-		validateRequests: options.validateRequests,
-		validateResponses: options.validateResponses,
-		validateFormats: options.validateFormats,
+		$refParser,
+		coerceTypes,
+		fileUploader,
+		ignorePaths,
+		operationHandlers,
+		unknownFormats,
+		validateFormats,
+		validateRequests,
+		validateResponses,
+		validateSecurity,
 	}).install(app);
@@ -29,0 +49,0 @@

package.json

 {
   "name": "swagger-endpoint-validator",
-  "version": "2.0.2",
+  "version": "2.1.0",
   "description": "A validator of API endpoints to check that input and output match with the swagger specification for the API",
@@ -33,20 +33,19 @@ "main": "index.js",
     "debug": "^4.1.1",
+    "express-jsdoc-swagger": "^1.0.3",
     "express-openapi-validator": "^3.12.7",
-    "express-swagger-generator": "^1.1.17",
-    "js-yaml": "^3.13.1",
+    "js-yaml": "^3.14.0",
     "openapi-enforcer": "^1.10.3",
     "swagger-jsdoc": "^4.0.0",
-    "swagger-ui-express": "^4.1.4",
-    "swagger2openapi": "^6.0.3"
+    "swagger-ui-express": "^4.1.4"
   },
   "devDependencies": {
     "body-parser": "^1.19.0",
-    "eslint": "^6.8.0",
-    "eslint-config-airbnb-base": "^14.1.0",
-    "eslint-plugin-import": "^2.20.2",
-    "eslint-plugin-jest": "^23.9.0",
+    "eslint": "^7.5.0",
+    "eslint-config-airbnb-base": "^14.2.0",
+    "eslint-plugin-import": "^2.22.0",
+    "eslint-plugin-jest": "^23.18.0",
     "express": "^4.17.1",
     "husky": "^4.2.5",
-    "jest": "^26.0.1",
-    "jest-junit": "^10.0.0",
+    "jest": "^26.1.0",
+    "jest-junit": "^11.0.1",
     "supertest": "^4.0.2"
@@ -53,0 +52,0 @@ },

test/jsdoc/e2e.test.js

@@ -31,2 +31,3 @@ const request = require('supertest');
 				.send({ name: 'my new pet' });
+
 			expect(res.statusCode)
@@ -47,3 +48,3 @@ .toEqual(200);
 
-		// TODO: it's not possible to do query params values validation with JSDoc
+		// TODO: it's not possible to do query params minimum and maximum values validation with JSDoc
 		test.skip('should return a bad request error (400) when GET request query params are not valid', async () => {
@@ -58,2 +59,11 @@ const res = await request(app)
 
+		test('should return a bad request error (400) when GET request query param type is not valid', async () => {
+			const res = await request(app)
+				.get('/pets?limit=string');
+			expect(res.statusCode)
+				.toEqual(400);
+			expect(res.body.message)
+				.toEqual('request.query.limit should be integer');
+		});
+
 		test('should return a bad request error (400) when POST request body is not valid', async () => {
@@ -60,0 +70,0 @@ const res = await request(app)

test/jsdoc/fake-server.js

@@ -31,29 +31,28 @@ const express = require('express');
 		validationEndpoint: '/test',
-		validateRequests: true,
-		validateResponses: true,
 		apiDocEndpoint: '/docs',
 		format: 'jsdoc',
 		jsdoc: {
-			swaggerDefinition: {
-				info: {
-					version: '1.0.0',
-					title: 'Swagger Petstore',
-					description: 'A sample API that uses a petstore as an example to demonstrate features in the OpenAPI 3.0 specification',
-					termsOfService: 'http://swagger.io/terms/',
-					contact: {
-						name: 'Swagger API Team',
-						email: '[e-mail]',
-						url: 'http://swagger.io',
-					},
-					license: {
-						name: 'Apache 2.0',
-						url: 'https://www.apache.org/licenses/LICENSE-2.0.html',
-					},
+			info: {
+				description: 'Documentation for API',
+				title: 'API Title',
+				version: '1.0.0',
+				license: {
+					name: 'MIT',
 				},
+				contact: {
+					name: 'Author',
+					email: '[e-mail]',
+				},
 			},
-			basedir: process.cwd(),
-			files: [
-				'./test/jsdoc/fake-server.js',
-				'./test/jsdoc/components.js',
-			],
+			servers: [],
+			security: {
+				JWT: {
+					type: 'apiKey',
+					in: 'header',
+					name: 'Authorization',
+				},
+			},
+			baseDir: __dirname,
+			swaggerUIPath: '/docs/api',
+			filesPattern: './fake-server.js',
 		},
@@ -63,10 +62,27 @@ });
 	/**
-	 * @route GET /pets
+	 * @typedef {object} Pet
+	 * @property {integer} id.required
+	 * @property {string} name.required
+	 * @property {string} tag
+	 */
+
+	/**
+	 * @typedef {object} NewPet
+	 * @property {string} name.required
+	 * @property {string} tag
+	 */
+
+	/**
+	 * @typedef {object} Error
+	 * @property {integer} code.required
+	 * @property {string} message.required
+	 */
+
+	/**
+	 * GET /pets
 	 * @summary Returns all pets from the system that the user has access to
-	 * @param {[string]} tags.query - tags to filter by
 	 * @param {integer} limit.query - maximum number of results to return
 	 * @param {boolean} wrong.query - flag to force the server to return invalid response
-	 * @produces application/json
-	 * @returns {Array.<Pet>} 200 - pet response
-	 * @returns {Error.model} default - unexpected error
+	 * @return {array<Pet>} 200 - pet response
+	 * @return {Error} default - unexpected error
 	 */
@@ -86,8 +102,7 @@ app.get(
 	/**
-	 * @route POST /pets
+	 * POST /pets
 	 * @summary Creates a new pet in the store. Duplicates are allowed
-	 * @param {NewPet.model} body.body.required - Pet to add to the store
-	 * @produces application/json
-	 * @returns {Pet.model} 200 - pet response
-	 * @returns {Error.model} default - unexpected error
+	 * @param {NewPet} request.body.required - Pet to add to the store
+	 * @return {Pet} 200 - pet response
+	 * @return {Error} default - unexpected error
 	 */
@@ -94,0 +109,0 @@ app.post(

test/yaml_jsdoc/fake-server.js

@@ -31,4 +31,2 @@ const express = require('express');
 		validationEndpoint: '/test',
-		validateRequests: true,
-		validateResponses: true,
 		apiDocEndpoint: '/docs',
@@ -35,0 +33,0 @@ format: 'yaml_jsdoc',

test/yaml/fake-server.js

@@ -31,4 +31,2 @@ const express = require('express');
 		validationEndpoint: '/test',
-		validateRequests: true,
-		validateResponses: true,
 		apiDocEndpoint: '/docs',
@@ -35,0 +33,0 @@ format: 'yaml',

No alert changes

Improved metrics

Total package byte prevSize

49707

increased by0.31%

Dependency count

7

decreased by-12.5%

Lines of code

1053

increased by0.86%

Worsened metrics

Number of package files

27

decreased by-3.57%

Dependency changes

• + Addedexpress-jsdoc-swagger@^1.0.3

• + Addedchalk@4.1.2(transitive)

• + Addedexpress-jsdoc-swagger@1.8.0(transitive)

• + Addedhas-flag@4.0.0(transitive)

• + Addedmerge@2.1.1(transitive)

• + Addedsupports-color@7.2.0(transitive)

• - Removedexpress-swagger-generator@^1.1.17

• - Removedswagger2openapi@^6.0.3

• - Removed@babel/code-frame@7.24.2(transitive)

• - Removed@babel/helper-validator-identifier@7.22.20(transitive)

• - Removed@babel/highlight@7.24.2(transitive)

• - Removed@babel/runtime@7.24.4(transitive)

• - Removed@exodus/schemasafe@1.3.0(transitive)

• - Removedajv@5.5.2(transitive)

• - Removedansi-regex@5.0.1(transitive)

• - Removedansi-styles@3.2.1(transitive)

• - Removedbetter-ajv-errors@0.6.7(transitive)

• - Removedcamelcase@5.3.1(transitive)

• - Removedchalk@2.4.2(transitive)

• - Removedcliui@6.0.08.0.1(transitive)

• - Removedco@4.6.0(transitive)

• - Removedcode-error-fragment@0.0.230(transitive)

• - Removedcolor-convert@1.9.3(transitive)

• - Removedcolor-name@1.1.3(transitive)

• - Removedcore-js@2.6.123.37.0(transitive)

• - Removeddebug@3.2.7(transitive)

• - Removeddecamelize@1.2.0(transitive)

• - Removeddoctrine@2.1.0(transitive)

• - Removeddoctrine-file@1.0.3(transitive)

• - Removedemoji-regex@8.0.0(transitive)

• - Removedes6-promise@3.3.1(transitive)

• - Removedescalade@3.1.2(transitive)

• - Removedescape-string-regexp@1.0.5(transitive)

• - Removedexpress-swagger-generator@1.1.17(transitive)

• - Removedexpress-swaggerize-ui@1.1.0(transitive)

• - Removedfast-deep-equal@1.1.0(transitive)

• - Removedfast-safe-stringify@2.1.1(transitive)

• - Removedfind-up@4.1.0(transitive)

• - Removedformat-util@1.0.5(transitive)

• - Removedget-caller-file@2.0.5(transitive)

• - Removedgrapheme-splitter@1.0.4(transitive)

• - Removedhas-flag@3.0.0(transitive)

• - Removedhttp2-client@1.3.5(transitive)

• - Removedis-fullwidth-code-point@3.0.0(transitive)

• - Removedjs-tokens@4.0.0(transitive)

• - Removedjson-schema-ref-parser@5.1.3(transitive)

• - Removedjson-schema-traverse@0.3.1(transitive)

• - Removedjson-to-ast@2.1.0(transitive)

• - Removedjsonpointer@4.1.0(transitive)

• - Removedjsonschema@1.2.4(transitive)

• - Removedjsonschema-draft4@1.0.0(transitive)

• - Removedleven@3.1.0(transitive)

• - Removedlocate-path@5.0.0(transitive)

• - Removednode-fetch-h2@2.3.0(transitive)

• - Removednode-readfiles@0.2.0(transitive)

• - Removedoas-kit-common@1.0.8(transitive)

• - Removedoas-linter@3.2.2(transitive)

• - Removedoas-resolver@2.5.6(transitive)

• - Removedoas-schema-walker@1.1.5(transitive)

• - Removedoas-validator@4.0.8(transitive)

• - Removedono@4.0.11(transitive)

• - Removedopenapi-schema-validation@0.4.2(transitive)

• - Removedp-limit@2.3.0(transitive)

• - Removedp-locate@4.1.0(transitive)

• - Removedp-try@2.2.0(transitive)

• - Removedpath-exists@4.0.0(transitive)

• - Removedpicocolors@1.0.0(transitive)

• - Removedrecursive-iterator@2.0.3(transitive)

• - Removedreftools@1.1.9(transitive)

• - Removedregenerator-runtime@0.14.1(transitive)

• - Removedrequire-directory@2.1.1(transitive)

• - Removedrequire-main-filename@2.0.0(transitive)

• - Removedset-blocking@2.0.0(transitive)

• - Removedshould@13.2.3(transitive)

• - Removedshould-equal@2.0.0(transitive)

• - Removedshould-format@3.0.3(transitive)

• - Removedshould-type@1.4.0(transitive)

• - Removedshould-type-adaptors@1.1.0(transitive)

• - Removedshould-util@1.0.1(transitive)

• - Removedstring-width@4.2.3(transitive)

• - Removedstrip-ansi@6.0.1(transitive)

• - Removedsupports-color@5.5.0(transitive)

• - Removedswagger-methods@1.0.8(transitive)

• - Removedswagger-parser@5.0.6(transitive)

• - Removedswagger-schema-official@2.0.0-bab6bed(transitive)

• - Removedswagger2openapi@6.2.3(transitive)

• - Removedvalidator@10.11.0(transitive)

• - Removedwhich-module@2.0.1(transitive)

• - Removedwrap-ansi@6.2.07.0.0(transitive)

• - Removedy18n@4.0.35.0.8(transitive)

• - Removedyaml@1.10.2(transitive)

• - Removedyargs@15.4.117.7.2(transitive)

• - Removedyargs-parser@18.1.321.1.1(transitive)

• - Removedz-schema@3.25.1(transitive)

• Updatedjs-yaml@^3.14.0