Fastify动态模式下Swagger UI不显示路由问题求助

核心排查方向 #

动态模式下Swagger无法识别路由，主要原因是路由注册时机早于Swagger插件初始化，或路由Schema不符合OpenAPI规范。

修复步骤 #

• 严格控制插件注册顺序：必须先注册@fastify/swagger和@fastify/swagger-ui，再注册业务路由。示例代码：

  const fastify = require('fastify')({ logger: true })
  
  // 先注册Swagger相关插件
  await fastify.register(require('@fastify/swagger'), {
    openapi: {
      info: { title: 'Test API', version: '0.1.0' },
      servers: [{ url: 'http://localhost:3000' }]
    },
    mode: 'dynamic' // 显式开启动态模式
  })
  
  await fastify.register(require('@fastify/swagger-ui'), {
    routePrefix: '/docs'
  })
  
  // 再注册业务路由
  fastify.get('/ping', {
    schema: {
      response: {
        200: {
          type: 'object',
          properties: { pong: { type: 'string' } }
        }
      }
    }
  }, async (req, reply) => {
    return { pong: 'pong' }
  })
  
  await fastify.listen({ port: 3000 })
  

• 校验路由Schema合法性：每个路由的schema需包含至少一个可被Swagger识别的字段（如response、parameters），避免使用不符合OpenAPI规范的类型或结构。
• 验证动态模式配置：确保@fastify/swagger配置中明确设置mode: 'dynamic'（默认虽为动态，但显式声明可避免隐式问题）。
• 重置依赖环境：删除node_modules和package-lock.json后重新安装，排除版本兼容或缓存问题：

  rm -rf node_modules package-lock.json
  npm install
  

• 调试生成结果：访问/docs/json查看Swagger JSON输出，若paths为空，说明路由未被抓取，重点检查注册顺序；若有内容但UI不显示，清理浏览器缓存或检查swagger-ui的路由前缀配置。

额外注意 #

若使用插件封装路由，需确保封装内的路由在Swagger插件注册完成后再加载，否则动态模式无法监听路由注册事件。

内容的提问来源于stack exchange，提问作者aCodeOrNot