Missing description when using $ref

[melroy89]

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the bug has not already been reported

Fastify version

4.26.2

Plugin version

8.14.0

Node.js version

20.11.1

Operating system

Linux

Operating system version (i.e. 20.04, 11.3, 10)

Linux Mint 23.1

Description

When adding shared schemas via fastify.addSchema() for response objects and using the id to access the schema like so: 422: { $ref: 'internalServerErrorResponse#' }, result in a missing description.

Instead of the description displayed from the added schema, you will keep seeing "Default Response". When not using shared ref schemas, but adding the schema to the route schema, the description is taking into account. So it only doesn't work when using ref.

Steps to Reproduce

1. Add shared schema for a response including a description, like this:

import fastify from 'fastify'
import fastifySwagger from '@fastify/swagger'
import fastifySwaggerUi from '@fastify/swagger-ui'

const fastify = fastify()

fastify.addSchema({
  $id: 'validationError',
  description: 'Validation Error',
  type: 'object',
  properties: {
    statusCode: { type: 'number' },
    code: { type: 'string' },
    error: { type: 'string' },
    message: { type: 'string' }
  }
})

// Use OpenAPI v3 spec
await fastify.register(fastifySwagger, {
      mode: 'dynamic',
      openapi: { }
})
// Also add Swagger-UI plugin
await fastify.register(fastifySwaggerUi, {
  routePrefix: '/docs',
})

Using this schema by ID:

fastify.delete('/:id', { schema: {
  description: 'Delete an object (example)',
  response: {
    422: {
      $ref: 'validationError#'
    },
}, async (req, reply) => {
  // ...
})

Going to the /docs for swagger, you will see:

Expected Behavior

The description of the schema should be put in the response description as well, instead of showing "Default Response" (which is the fallback description text).

Code

I don't know the codebase, and utils.js is quite complex code. But I suspect to look around there:

fastify-swagger/lib/spec/openapi/utils.js

Line 342 in fedf75c

const resolved = transformDefsToComponents(ref.resolve(rawJsonSchema))

[melroy89]

I also tried Scalar, I see the same "Default response" message (instead of using the description) when using Scalar api reference interface with $ref responses: