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:

[melroy89]

@jean-michelet Would you be willing to help me with this issue? To briefly explain the issue. You can use Fastify with swagger as you know, using schemas.

So I'm using fastify.addSchema() to add multiple shared schemas, right? Nothing wrong there. Then you can access those shared schemas using this $ref notation like so:

    422: {
      $ref: 'validationError#'
    },

However, for some reason when going to the Fastify Swagger docs, the response description is not copied correctly and all the shared schemas will just show "Default Response" no matter what.. The reason you didn't saw this problem in your demo repo is because you aren't using the addSchema feature: https://fastify.dev/docs/latest/Reference/Validation-and-Serialization/#adding-a-shared-schema

The same issue appears both in Swagger as well as Scalar. I suspect it's using the same code.

[jean-michelet]

Should we use addSchema in the demo?

[jean-michelet]

If not, I don't know if I have time to fix this. Fastify mainteners usually don't fix bugs that don't affect them directly, expect security issues I guess. Can you push a PR with unit tests?

[melroy89]

Should we use addSchema in the demo?

Maybe not a bad idea.. It's a good example how you could re-use schemas in Fastify.

[Nelspike]

I just went ahead and opened a PR to solve this - Hopefully it helps! 🎉 #826

[jean-michelet]

Thanks @Nelspike!