Allow partial schema override for ApiResponses

[tmtron]

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

When using the @ApiResponse decorators, we need to use the type and override some schema properties: e.g. the example.

This is currently not possible.

Describe the solution you'd like

The @ApiResponse decorators, should "merge" an explicit schema to the schema generated from the type.

Stackblitz example

In the following decorator, the schema example is ignored and instead the default example (generated from the DTO properties is used):

  @ApiCreatedResponse({
    description: 'new cat created',
    type: Cat,
    schema: {
      example: {
        name: 'this is ingoed!',
        age: 11,
        breed: 'mixed',
      },
    },
  })

Teachability, documentation, adoption, migration strategy

I think toRefObject could be changed to not override the whole schema, but only $ref, e.g.

Index: lib/services/response-object-mapper.ts
IDEA additional info:
Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP
<+>UTF-8
===================================================================
diff --git a/lib/services/response-object-mapper.ts b/lib/services/response-object-mapper.ts
--- a/lib/services/response-object-mapper.ts	(revision 40106817a268820cdc5c46536048bc3c8887e38e)
+++ b/lib/services/response-object-mapper.ts	(date 1639386662284)
@@ -29,6 +29,7 @@
       ...response,
       ...this.mimetypeContentWrapper.wrap(produces, {
         schema: {
+          ...response.schema,
           $ref: getSchemaPath(name)
         }
       })

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

The motivation is to be able to mix type and explicit schema

[kamilmysliwiec]

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.