TypeScript配置@fastify/swagger及swagger-ui遇路由文档不显示问题排查

核心问题：插件注册的异步顺序错误 #

Fastify 的 register 方法是异步操作，你当前的代码在未等待 fastifySwagger 和 fastifySwaggerUi 插件注册完成的情况下，直接同步注册了根路由，导致 Swagger 插件无法捕获到该路由的 Schema 信息，因此文档页面不会显示该路由。

次要问题与优化点 #

1. Swagger 配置中的 servers 地址缺少端口，与实际运行端口不匹配
2. fastify.swagger() 的调用时机错误，该方法应在所有路由注册完成后、服务启动前调用（或可省略，插件会自动处理）

修复后的代码示例 #

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

import { errorBoundary } from './plugins/errorBoundary';

const fastify = Fastify({
  logger: true
});

const port = process.env.PORT || 3003;

// 设置自定义错误处理器
fastify.setErrorHandler(errorBoundary);

async function start() {
  // 先等待Swagger插件注册完成
  await fastify.register(fastifySwagger, {
    openapi: {
      info: {
        title: 'Forest Fire API',
        description: 'Forest Fire API Documentation',
        version: '1.0.0'
      },
      servers: [
        {
          // 补充端口，与实际运行端口一致
          url: `http://localhost:${port}`
        }
      ],
      components: {
        securitySchemes: {
          bearerAuth: {
            type: 'http',
            scheme: 'bearer'
          }
        }
      },
      tags: [
        {
          name: 'Root',
          description: 'Root endpoints'
        }
      ]
    }
  });

  // 等待Swagger UI插件注册完成
  await fastify.register(fastifySwaggerUi, {
    routePrefix: '/docs',
    uiConfig: {
      docExpansion: 'full',
      deepLinking: false
    },
    uiHooks: {
      onRequest: function (_request, _reply, next) {
        next();
      },
      preHandler: function (_request, _reply, next) {
        next();
      }
    },
    staticCSP: true,
    transformStaticCSP: (header) => header,
    transformSpecification: (swaggerObject) => {
      return swaggerObject;
    },
    transformSpecificationClone: true
  });

  // 插件注册完成后再注册路由
  fastify.get(
    '/',
    {
      schema: {
        description: 'Root endpoint',
        tags: ['Root'],
        response: {
          200: {
            // 修正拼写错误（可选）
            description: 'Successful response',
            type: 'object',
            properties: {
              message: { type: 'string' },
              result: { type: 'object', nullable: true }
            }
          }
        }
      }
    },
    async function (request, reply) {
      return reply.send({
        message: 'Hello World',
        result: null
      });
    }
  );

  // 启动服务
  await fastify.listen({
    port: port as number
  });

  // 可选：手动生成Swagger文档，插件通常会自动处理
  // fastify.swagger();
}

start().catch((err) => {
  fastify.log.error(err);
  process.exit(1);
});

其他排查点 #

• 检查是否有其他插件或错误处理器干扰了Swagger的Schema收集
• 确认@fastify/swagger和@fastify/swagger-ui的版本与Fastify版本兼容（建议使用最新稳定版）

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