fastify/help

allOf with property override returns serialization crash

Closed this issue ยท 1 comments

You have already researched for similar issues?

This issue seems related #1053

๐Ÿ’ฌ Question here

I was formerly using swagger-jsdoc to generate OpenAPI spec for an Express API.

We are moving on Fastify and fastify-swagger seems very well integrated in the fastify ecosystem, then I tried removing swagger-jsdoc in favor of fastify-swagger.

With JSdoc I was doing this:

 /**
 *    ...
 *    responses:
 *      200:
 *        content:
 *          "application/json":
 *            schema:
 *              allOf:
 *                - $ref: '#/components/schemas/PaginatedDto'
 *                - type: array
 *                  properties:
 *                    data:
 *                      $ref: '#/components/schemas/PurchaseItemDto'

This permit to override the property data of the referenced schema PaginatedDto with another ref named PurchaseItemDto.
Here is the result of this allOf schema:

dwedwe

FYI here is the initial PaginatedDto schema object:

Screenshot 2024-12-19 at 09 20 20

I "translated" the same thing on a schema used in fastify-swagger like this piece of code:

I tried the exactly same object also, with content and schema keys

response: {
      200: {
        allOf: [{
          $ref: 'PaginatedDto',
        }, {
          type: 'array',
          properties: {
            data: {
              $ref: 'PurchaseItemDto',
            }
          }
        }],
      },
    },

This result in the serialization error when starting the fastify app

FastifyError [Error]: Failed building the serialization schema for GET: /api/purchases, due to error Failed to merge "type" keyword schemas.
    at Boot.<anonymous> (/Users/mac/Documents/Projects/bff-next-gen/node_modules/.pnpm/fastify@5.1.0/node_modules/fastify/lib/route.js:401:21)
    at Object.onceWrapper (node:events:633:28)
    at Boot.emit (node:events:531:35)
    at /Users/mac/Documents/Projects/bff-next-gen/node_modules/.pnpm/avvio@9.1.0/node_modules/avvio/boot.js:102:12
    at /Users/mac/Documents/Projects/bff-next-gen/node_modules/.pnpm/avvio@9.1.0/node_modules/avvio/boot.js:437:7
    at done (/Users/mac/Documents/Projects/bff-next-gen/node_modules/.pnpm/avvio@9.1.0/node_modules/avvio/lib/plugin.js:228:5)
    at check (/Users/mac/Documents/Projects/bff-next-gen/node_modules/.pnpm/avvio@9.1.0/node_modules/avvio/lib/plugin.js:252:9)
    at node:internal/process/task_queues:151:7
    at AsyncResource.runInAsyncScope (node:async_hooks:211:14)
    at AsyncResource.runMicrotask (node:internal/process/task_queues:148:8) {
  code: 'FST_ERR_SCH_SERIALIZATION_BUILD',
  statusCode: 500
}

I don't know if the allOf usage I do is valid or not but the OpenAPI doc seems to allowing this.

I don't know if this is a bug of the fastify swagger serializer or if I missed something on my spec.

Is someone already did that? I a fastify swagger bug or not?

Thanks for helping ๐Ÿ˜„

Your Environment

  • node version: >22
  • fastify version: >=5.1.0
  • fastify swagger version": >=9.4.0
  • os: Mac
  • OpenAPI spec version: 3.1.0

I seems to find a way (thanks to copilot for the examples ๐Ÿ™Œ)

This schema fixes the serialization error and shows the correct response schema on the UI.

response: {
      200: {
        allOf: [{
          $ref: 'PaginatedDto',
        }, {
          type: 'object',
          properties: {
            data: {
              type: 'array',
              items: {
                $ref: 'PurchaseItemDto',
              }
            }
          }
        }],
      },
    },