Plugins must be imported at the top to propagate the types

[mikicho]

Prerequisites

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

Fastify version

3.29.1

Plugin version

6.1.0

Node.js version

16.15.0

Operating system

Linux

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

Debian 11.3

Description

typescript throw error when trying to add description or summary to endpoints:

fastify.post<{ Body: MyBody}>(
    '/generate',
    {
        schema: {
            description:  'my beautiful description', // <-- type error
            body: myBody,
        },
    },
    handler,
);

This is supported according to @fastify/swagger:

Also, if I'm ignore the error with // @ts-ignore it's working correctly and the swagger is valid

Steps to Reproduce

Almost identical to @fastify/swagger example.

1. save the below code to a file (a.ts)
2. run npx tsc --noEmit a.ts

import fastify from 'fastify';
const server = fastify();
(async () => {

await server.register(require('@fastify/swagger'), {
  routePrefix: '/documentation',
  swagger: {
    info: {
      title: 'Test swagger',
      description: 'Testing the Fastify swagger API',
      version: '0.1.0'
    },
    externalDocs: {
      url: 'https://swagger.io',
      description: 'Find more info here'
    },
    host: 'localhost',
    schemes: ['http'],
    consumes: ['application/json'],
    produces: ['application/json'],
    tags: [
      { name: 'user', description: 'User related end-points' },
      { name: 'code', description: 'Code related end-points' }
    ],
    definitions: {
      User: {
        type: 'object',
        required: ['id', 'email'],
        properties: {
          id: { type: 'string', format: 'uuid' },
          firstName: { type: 'string' },
          lastName: { type: 'string' },
          email: {type: 'string', format: 'email' }
        }
      }
    },
    securityDefinitions: {
      apiKey: {
        type: 'apiKey',
        name: 'apiKey',
        in: 'header'
      }
    }
  },
  uiConfig: {
    docExpansion: 'full',
    deepLinking: false
  },
  uiHooks: {
    onRequest: function (request, reply, next) { next() },
    preHandler: function (request, reply, next) { next() }
  },
  staticCSP: true,
  transformStaticCSP: (header) => header,
  exposeRoute: true
})

server.put('/some-route/:id', {
  schema: {
    description: 'post some data',
    tags: ['user', 'code'],
    summary: 'qwerty',
    params: {
      type: 'object',
      properties: {
        id: {
          type: 'string',
          description: 'user id'
        }
      }
    },
    body: {
      type: 'object',
      properties: {
        hello: { type: 'string' },
        obj: {
          type: 'object',
          properties: {
            some: { type: 'string' }
          }
        }
      }
    },
    response: {
      201: {
        description: 'Successful response',
        type: 'object',
        properties: {
          hello: { type: 'string' }
        }
      },
      default: {
        description: 'Default response',
        type: 'object',
        properties: {
          foo: { type: 'string' }
        }
      }
    },
    security: [
      {
        "apiKey": []
      }
    ]
  }
}, (req, reply) => {})

await server.ready()
server.swagger()

})();

Expected Behavior

no type error

[climba03003]

It is the problem of TypeScript itself.
Doing server.register(require('@fastify/swagger')) will not import the types augmentation properly.

Please import the package on top.

import FastifySwagger from '@fastify/swagger'

server.register(FastifySwagger)

[mcollina]

@climba03003 have we documented that on our docs?

[mikicho]

I can't find it even now. When I know what I'm looking for

[mcollina]

This would be a great addition to our docs! Would you like to send a PR?

[mikicho]

@mcollina sure. Do you think it should be in this repo or in fastify/swagger repo?

[mcollina]

this repo, in the typescript docs

[climba03003]

Yes, we do not have document anything on it.
And think it is not even in TypeScript. But, it is how TypeScript works currently and the behavior will be vary on config or even after certain updates.

Are we necessary to document how TypeScript behave?

[mikicho]

@climba03003 I agree, but the docs should tackle also pitfalls. we of course don't need to elaborate on the matters but may at least put a reference or link to the relevant information.