nestjs/swagger

Add an @ApiFileUpload decorator to support file upload

demmorou opened this issue · 1 comments

Is there an existing issue that is already proposing this?

  • I have searched the existing issues

Is your feature request related to a problem? Please describe it

It's not a problem. But I think it can improve the developer experience and help make your code cleaner.

When working with file uploads, we do not have a specific resource to document this upload. It is necessary to adapt and add a few more decorators to specify file fields, etc. This can make the code verbose and difficult to read.

Describe the solution you'd like

To solve this, I propose to create a new decorator @ApiFileUpload to abstract the logic of documenting the upload of a single or multiple files. It's possible using native resources.

How it works today:

@Patch('/picture')
@ApiConsumes('multipart/form-data')
@ApiBody({
    schema: {
      type: 'object',
      properties: { picture: { type: 'string', format: 'binary' } },
    },
  })
uploadSingleFile() {
    // same logic here
}

@Patch('/pictures')
@ApiConsumes('multipart/form-data')
@ApiBody({
    schema: {
      type: 'object',
      properties: {
        picture1: { type: 'string', format: 'binary' },
        picture2: { type: 'string', format: 'binary' },
        picture3: { type: 'string', format: 'binary' },
      },
    },
  })
uploadMultipleFiles() {
    // same logic here
}

With my proposal:

@Patch('/picture')
@ApiFileUpload('picture1')
uploadSingleFile() {
    // same logic here
}

@Patch('/pictures')
@ApiFileUpload('picture1', 'picture2', 'picture3')
uploadMultipleFiles() {
    // same logic here
}

Teachability, documentation, adoption, migration strategy

No response

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

My motivation came when I needed to use a resource like this but couldn't find it natively. So I implemented it in the project in question and it completely solved my problem.

I managed to make the code cleaner without leaving aside good documentation.

Captura de Tela 2024-02-10 às 10 21 56

This appear in portuguese because I'm Brazilian

This is in a production environment and will certainly be used in other projects that have the same need.

Thanks for your suggestion!

This has been discussed in the past and we decided to not implement it in the foreseeable future.

If you think your request could live outside Nest's scope, we'd encourage you to collaborate with the community on publishing it as an open source package.