Support adding response examples when using $ref

[djbb7]

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 $ref as the response type of an endpoint, the other properties of the decorator (such as examples) are ignored. According to the openapi 3.0 spec:

If schema refers to some object defined in the components section, then you should make example a child of the media type keyword. This is needed because $ref overwrites all the siblings alongside it.

With the current implementation of this library it is only possible to add examples under schema

My use case is defining a general Error response DTO, and adding specific examples for each response code.

@ApiForbiddenResponse(
{
	description: 'Unauthorized.',
	type: HttpExceptionDTO,
	schema: {
		example: {
			message: 'Unauthorized',
			status: 403
		}
	}
)
@ApiNotFoundResponse(
	{
	description: 'Unauthorized.',
	type: HttpExceptionDTO,
	schema: {
		example: {
			message: 'Unauthorized',
			status: 404
		}
	}
)

Describe the solution you'd like

The solution would be to support defining examples/example at the top-level of the decorator rather than nested under schema.

{
	description: 'Unauthorized.',
	type: HttpExceptionDTO,
	example: {
		message: 'Unauthorized',
		status: 403
	}
)
@ApiNotFoundResponse(
	{
	description: 'Unauthorized.',
	type: HttpExceptionDTO,
	example: {
		message: 'Unauthorized',
		status: 404
	}
)

Teachability, documentation, adoption, migration strategy

No response

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

To support adding examples alongside $ref.

[kamilmysliwiec]

Would you like to create a PR for this?

[alexproca]

I also have a similar problem. I miss the example functionality on @ApiOkResponse().

My workaround is:

    @ApiOkResponse({
      content: {
        'application/json': {
          schema: {
            type: 'array',
            items: {
              $ref: '#/components/schemas/CatDTO',
            }
          },
          example: [{
            name: 'Tom'
          }]
        }
      }
    })

But I would like to write it like this:

@ApiOkResponse({
      type: CatDTO,
      isArray: true,
      example: [{
        name: 'Tom'
      }]
    })

And the renderer would use my example and not try to infer the example based on the CatDTO. The practical usage for this Is that I have a fairly big DTO with a lot of optional fields and the swagger UI freezes trying to generate an example.

[shaunhurryup]

@alexproca Thanks bro! Other than a little verbose, that's fine 👍

My workaround is:

    @ApiOkResponse({
      content: {
        'application/json': {
          schema: {
            type: 'array',
            items: {
              $ref: '#/components/schemas/CatDTO',
            }
          },
          example: [{
            name: 'Tom'
          }]
        }
      }
    })