Nest: Document the proper use of multipart/form-data uploads and how to use them with swagger module

[farcaller]

I'm submitting a...

[ ] Regression 
[ ] Bug report
[x] Feature request
[x] Documentation issue or request
[ ] Support request => Please do not submit support request here, instead post your question on Stack Overflow.

Current behavior

There's very little documentation on how to handle binary uploads, e.g. multipart/form-data. There are a few issues opened to figure the nest integration with multer, which mostly works. This is a solution mostly external to nest, though, and, as a result, it's not propagated to swagger. Swagger has some support for multipart upload though.

Expected behavior

• [ ] There's a document describing how to set up file upload with nest, using multer or whatever.
• [ ] It should work with the swagger module.

What is the motivation / use case for changing the behavior?

Files upload is a rather common use case. Swagger module is awesome and needs to support this too 😄

[myflowpl]

any news on this?
@kamilmysliwiec does 'docs' label means it's possible right now but not documented ?

[farcaller]

It's clearly possible and I've done it—but I'm not sure if what I did is the "best practice".

[myflowpl]

@farcaller let's skip best practices for now :)
let us just get the code work, later we will think about refactoring
so can you post for us some code examples ?

[farcaller]

Here's my handler:

@Post()
@ApiResponse({status: 201, description: 'Created', type: Photo})
async create(@Request() req): Promise<Photo> {
  const f = req.files[0];
  ...

with the following mutter middleware:

@Middleware()
export class MulterMiddleware implements NestMiddleware {
  resolve(): (req, res, next) => void {
    const upload = multer({ dest: './uploads' });
    return upload.any();
  }
}

(for whatever reason it had to go into a dedicated file)

Attached like this in the module:

export class PhotosModule {
  public configure(consumer: MiddlewaresConsumer) {
    consumer
      .apply(MulterMiddleware).forRoutes({ path: 'photos', method: RequestMethod.POST });
  }
}

I generate the tepescript fetch client bindings via swagger and then do this on the client:

const formData: FormData = new FormData();
formData.append('file', file, file.name);
const photo = await this.api.photosPost({ body: formData });

Note that swagger api doesn't know anything about the attached file in this scenario, I work it around in the server handler via the extension to req and on the client via the optional parameters to an otherwise empty request.

[kamilmysliwiec]

As mentioned here https://github.com/nestjs/nest/issues/262, now Nest provides some additional decorators that help with multer integration. It should be a better starting point with swagger integration as well. 🙂

[MRisto]

Any updates on the documentation?

[kamilmysliwiec]

It is a part of the new documentation: https://docs.nestjs.com/v5
Techniques -> File upload

I'll merge it once Nest hits v5.0.0.

[jienco]

I like very much the new file upload implementation with multer, thank you very much for the hard work. It would be wounderful to integrate it with swagger-generated documentation. I tried it without success... Can someone tell me how to use the file upload it with swagger?

[lock[bot]]

This thread has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.