Define multiple Output Formats (NEXT VERSION)

I’m submitting a…

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

!!! Note that i am using the @next branch (4.0.0-next.3) !!!

Dear @kamilmysliwiec ,

i am trying to implement the new Nest Swagger Package with my current application.

In this context, the Open API v3 specs allows to define multiple media types (accept headers) the user can request. For example, i am building an API that allows for application/json and application/vnd.api+json ( the json:api specs) requests. However, the data format sent to and returned from my backend differs - depending on the requested type (i.e., the structure differs).

This behaviour is described in the official Open API documentation as well: https://swagger.io/docs/specification/describing-responses/

Current behavior

I found, that the @ApiResponse() decorator allows for defining this content attribute. However, I am not able to “link” this specific response format to a particular model (by class-name itself) but only via full-qualified reference string name.

Take, for example, the following fully-decorated method

  @Get('account')
  @ApiOperation({
    summary: 'My Account',
    description:
      'Returns the Account (based on JWT) for the currently active User',
  })
  @ApiResponse({
    content: {
      'application/json': {
        schema: { $ref: '#/components/schemas/HttpAccountEntity' },
      },
      'application/vnd.api+json': {
        schema: { $ref: '#/components/schemas/JsonAccountEntity' },
      },
    },
    description: 'Default Response',
    status: 200,
  })
  async myAccount() {
    // do something
  }

With this, i need to use the fully qualified schema reference name as string, because the Response.content.*.schema.ref is defined as string.

For the sake of consistency (and minimizing errors) i think, it would be better to define it like this (only relevant part):

  @ApiResponse({
    content: {
      'application/json': {
-        schema: { $ref: '#/components/schemas/HttpAccountEntity' },
+       schema: { $ref: HttpAccountEntity },
      },
      'application/vnd.api+json': {
-        schema: { $ref: '#/components/schemas/JsonAccountEntity' },
+       schema: { $ref: JsonAccountEntity },
      },
    },
    description: 'Default Response',
    status: 200,
  })

Please note that I am actually not aware, if the schema.$ref property is the correct way to specify my desired behavior. I noticed, that there is also a schema.type: string, however, i was not able to get this to work properly!

  @ApiResponse({
    content: {
      'application/json': {
        schema: { type: HttpAccountEntity },
      },
      // ...
    },
    description: 'Default Response',
    status: 200,
  })

Environment

Nest Core: 6.8.5
Nest Swagger: 4.0.0-next.3

[kamilmysliwiec]

Take a look at this section in the documentation: https://docs.nestjs.com/recipes/swagger#extra-models

[nartc]

I’m interested in working on a PR for this. Sounds reasonable and better DX.