Merge pull request #205 from cdimascio/optional-file-upload

Optional file upload

README.md

@@ -336,7 +336,7 @@ new OpenApiValidator(options).install({
   },
   ignorePaths: /.*\/pets$/,
   unknownFormats: ['phone-number', 'uuid'],
-  multerOpts: { ... },
+  fileUploader: { ... } | true | false,
   $refParser: {
     mode: 'bundle'
   }
@@ -454,10 +454,22 @@ Defines how the validator should behave if an unknown or custom format is encoun
 
 - `"ignore"` - to log warning during schema compilation and always pass validation. This option is not recommended, as it allows to mistype format name and it won't be validated without any error message.
 
-### ▪️ multerOpts (optional)
+### ▪️ fileUploader (optional)
 
 Specifies the options to passthrough to multer. express-openapi-validator uses multer to handle file uploads. see [multer opts](https://github.com/expressjs/multer)
 
+- `true` (**default**) - enables multer and provides simple file(s) upload capabilities
+- `false` - disables file upload capability. Upload capabilities may be provided by the user
+- `{...}` - multer options to be passed-through to multer. see [multer opts](https://github.com/expressjs/multer) for possible options
+
+  e.g.
+
+  ```javascript
+  fileUploader: {
+    dest: 'uploads/';
+  }
+  ```
+
 ### ▪️ coerceTypes (optional)
 
 Determines whether the validator should coerce value types to match the type defined in the OpenAPI spec.
@@ -773,6 +785,10 @@ module.exports = app;
 
 **A:** In v3, `securityHandlers` have been replaced by `validateSecurity.handlers`. To use v3 security handlers, move your existing security handlers to the new property. No other change is required. Note that the v2 `securityHandlers` property is supported in v3, but deprecated
 
+Q: What happened to the `multerOpts` property?
+
+A: In v3, `multerOpts` have been replaced by `fileUploader`. In order to use the v3 `fileUploader`, move your multer options to `fileUploader` No other change is required. Note that the v2 `multerOpts` property is supported in v3, but deprecated
+
 **Q:** Can I use a top level await?
 
 **A:** Top-level await is currently a stage 3 proposal, however it can be used today with [babel](https://babeljs.io/docs/en/babel-plugin-syntax-top-level-await)

example/README.md

@@ -153,7 +153,10 @@ new OpenApiValidator({
   .then(app => {
     // 5. Define routes using Express
     app.get('/v1/pets', function(req, res, next) {
-      res.json([{ id: 1, name: 'max' }, { id: 2, name: 'mini' }]);
+      res.json([
+        { id: 1, name: 'max' },
+        { id: 2, name: 'mini' },
+      ]);
     });
 
     app.post('/v1/pets', function(req, res, next) {
@@ -364,7 +367,7 @@ new OpenApiValidator(options).install({
   validateResponses: true,
   ignorePaths: /.*\/pets$/
   unknownFormats: ['phone-number', 'uuid'],
-  multerOpts: { ... },
+  fileUploader: { ... },
   securityHandlers: {
     ApiKeyAuth: (req, scopes, schema) => {
       throw { status: 401, message: 'sorry' }
@@ -461,10 +464,22 @@ Defines how the validator should behave if an unknown or custom format is encoun
 
 - `"ignore"` - to log warning during schema compilation and always pass validation. This option is not recommended, as it allows to mistype format name and it won't be validated without any error message.
 
-### ▪️ multerOpts (optional)
+### ▪️ fileUploader (optional)
 
 Specifies the options to passthrough to multer. express-openapi-validator uses multer to handle file uploads. see [multer opts](https://github.com/expressjs/multer)
 
+- `true` (**default**) - enables multer and provides simple file(s) upload capabilities
+- `false` - disables file upload capability. Upload capabilities may be provided by the user
+- `{...}` - multer options to be passed-through to multer. see [multer opts](https://github.com/expressjs/multer) for possible options
+
+  e.g.
+
+  ```javascript
+  fileUploader: {
+    dest: 'uploads/';
+  }
+  ```
+
 ### ▪️ coerceTypes (optional)
 
 Determines whether the validator should coerce value types to match the type defined in the OpenAPI spec.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "express-openapi-validator",
-  "version": "3.3.1",
+  "version": "3.4.1",
   "description": "Automatically validate API requests and responses with OpenAPI 3 and Express.",
   "main": "dist/index.js",
   "scripts": {

src/framework/types.ts

@@ -1,4 +1,5 @@
 import * as ajv from 'ajv';
+import * as multer from 'multer';
 import { Request, Response, NextFunction } from 'express';
 export { OpenAPIFrameworkArgs };
 
@@ -55,7 +56,8 @@ export interface OpenApiValidatorOpts {
   securityHandlers?: SecurityHandlers;
   coerceTypes?: boolean | 'array';
   unknownFormats?: true | string[] | 'ignore';
-  multerOpts?: {};
+  fileUploader?: boolean | multer.Options;
+  multerOpts?: multer.Options;
   $refParser?: {
     mode: 'bundle' | 'dereference';
   };

src/index.ts

@@ -27,6 +27,7 @@ export class OpenApiValidator {
     if (options.validateRequests == null) options.validateRequests = true;
     if (options.validateResponses == null) options.validateResponses = false;
     if (options.validateSecurity == null) options.validateSecurity = true;
+    if (options.fileUploader == null) options.fileUploader = {};
     if (options.$refParser == null) options.$refParser = { mode: 'bundle' };
 
     if (options.validateResponses === true) {
@@ -83,7 +84,9 @@ export class OpenApiValidator {
 
     this.installPathParams(app, context);
     this.installMetadataMiddleware(app, context);
-    this.installMultipartMiddleware(app, context);
+    if (this.options.fileUploader) {
+      this.installMultipartMiddleware(app, context);
+    }
 
     const components = context.apiDoc.components;
     if (this.options.validateSecurity && components?.securitySchemes) {
@@ -218,6 +221,20 @@ export class OpenApiValidator {
       );
     }
 
+    const multerOpts = options.multerOpts;
+    if (securityHandlers != null) {
+      if (typeof multerOpts !== 'object' || Array.isArray(securityHandlers)) {
+        throw ono('multerOpts must be an object or undefined');
+      }
+      deprecationWarning('multerOpts is deprecated. Use fileUploader instead.');
+    }
+
+    if (options.multerOpts && options.fileUploader) {
+      throw ono(
+        'multerOpts and fileUploader may not be used together. Use fileUploader to specify upload options.',
+      );
+    }
+
     const unknownFormats = options.unknownFormats;
     if (typeof unknownFormats === 'boolean') {
       if (!unknownFormats) {
@@ -243,5 +260,9 @@ export class OpenApiValidator {
       };
       delete options.securityHandlers;
     }
+    if (options.multerOpts) {
+      options.fileUploader = options.multerOpts;
+      delete options.multerOpts;
+    }
   }
 }

src/middlewares/openapi.multipart.ts

@@ -12,10 +12,12 @@ const multer = require('multer');
 
 export function multipart(
   OpenApiContext: OpenApiContext,
-  multerOpts: {} = {},
+  multerOpts: {},
 ): OpenApiRequestHandler {
   const mult = multer(multerOpts);
   return (req, res, next) => {
+    // TODO check that format: binary (for upload) else do not use multer.any()
+    // use multer.none() if no binary parameters exist
     if (isMultipart(req) && isValidContentType(req)) {
       mult.any()(req, res, err => {
         if (err) {
@@ -35,7 +37,6 @@ export function multipart(
           // case we must follow the $ref to check the type.
 
           if (req.files) {
-
             // to handle single and multiple file upload at the same time, let us this initialize this count variable
             // for example { "files": 5 }
             const count_by_fieldname = (<Express.Multer.File[]>req.files)
@@ -46,18 +47,15 @@ export function multipart(
               }, {});
 
             // add file(s) to body
-            Object
-              .entries(count_by_fieldname)
-              .forEach(
-                ([fieldname, count]: [string, number]) => {
-                  // TODO maybe also check in the api doc if it is a single upload or multiple
-                  const is_multiple = count > 1;
-                  req.body[fieldname] = (is_multiple)
-                    ? new Array(count).fill('')
-                    : '';
-                },
-              );
-
+            Object.entries(count_by_fieldname).forEach(
+              ([fieldname, count]: [string, number]) => {
+                // TODO maybe also check in the api doc if it is a single upload or multiple
+                const is_multiple = count > 1;
+                req.body[fieldname] = is_multiple
+                  ? new Array(count).fill('')
+                  : '';
+              },
+            );
           }
           next();
         }
@@ -74,7 +72,9 @@ function isValidContentType(req: Request): boolean {
 }
 
 function isMultipart(req: OpenApiRequest): boolean {
-  return (<any>req?.openapi)?.schema?.requestBody?.content?.['multipart/form-data'];
+  return (<any>req?.openapi)?.schema?.requestBody?.content?.[
+    'multipart/form-data'
+  ];
 }
 
 function error(req: OpenApiRequest, err: Error): ValidationError {

src/middlewares/parsers/body.parse.ts

@@ -62,8 +62,8 @@ export class BodySchemaParser {
     requestBody: OpenAPIV3.RequestBodyObject,
   ): BodySchema {
     const bodyContentSchema =
-      requestBody.content[contentType.contentType] &&
-      requestBody.content[contentType.contentType].schema;
+      requestBody.content[contentType.withoutBoundary] &&
+      requestBody.content[contentType.withoutBoundary].schema;
 
     let bodyContentRefSchema = null;
     if (bodyContentSchema && '$ref' in bodyContentSchema) {

src/middlewares/util.ts

@@ -7,7 +7,7 @@ export class ContentType {
   public contentType: string = null;
   public mediaType: string = null;
   public charSet: string = null;
-  private withoutBoundary: string = null;
+  public withoutBoundary: string = null;
   private constructor(contentType: string | null) {
     this.contentType = contentType;
     if (contentType) {

test/common/app.common.ts

@@ -98,15 +98,15 @@ export function routes(app) {
     });
   });
 
-  app.post('/v1/pets/:id/photos', function(req: Request, res: Response): void {
-    // req.file is the `avatar` file
-    // req.body will hold the text fields, if there were any
-    const files = req.files;
-    res.status(200).json({
-      files,
-      metadata: req.body.metadata,
-    });
-  });
+  // app.post('/v1/pets/:id/photos', function(req: Request, res: Response): void {
+  //   // req.file is the `avatar` file
+  //   // req.body will hold the text fields, if there were any
+  //   const files = req.files;
+  //   res.status(200).json({
+  //     files,
+  //     metadata: req.body.metadata,
+  //   });
+  // });
   app.post('/v1/pets_charset', function(req: Request, res: Response): void {
     // req.file is the `avatar` file
     // req.body will hold the text fields, if there were any

test/common/app.ts

@@ -21,7 +21,6 @@ export async function createApp(
   app.use(bodyParser.json({ type: 'application/hal+json' }));
   app.use(bodyParser.text());
   app.use(logger('dev'));
-  app.use(express.json());
   app.use(express.urlencoded({ extended: false }));
   app.use(cookieParser());
   app.use(express.static(path.join(__dirname, 'public')));

test/common/myapp.ts

@@ -9,12 +9,12 @@ import { OpenApiValidator } from '../../src';
 
 const app = express();
 
-app.use(bodyParser.urlencoded());
+app.use(bodyParser.urlencoded({ extended: true }));
 app.use(bodyParser.text());
 app.use(bodyParser.json());
 app.use(logger('dev'));
-app.use(express.json());
-app.use(express.urlencoded({ extended: false }));
+// app.use(express.json());
+// app.use(express.urlencoded({ extended: true }));
 app.use(cookieParser());
 app.use(express.static(path.join(__dirname, 'public')));
 const spec = path.join(__dirname, 'openapi.yaml');
@@ -44,6 +44,13 @@ app.get('/v1/pets/:id', function(req: Request, res: Response): void {
   res.json({ id: req.params.id, name: 'sparky' });
 });
 
+app.get('/v1/pets/:id/form_urlencoded', function(
+  req: Request,
+  res: Response,
+): void {
+  res.json(req.body);
+});
+
 // 2a. Add a route upload file(s)
 app.post('/v1/pets/:id/photos', function(req: Request, res: Response): void {
   // DO something with the file