@fastify/swagger路由注册时$ref引用定义失败的问题咨询

核心原因 #

Fastify的路由Schema校验器（默认是Ajv）和Swagger文档生成是两个独立模块：

• Swagger配置里的definitions/components.schemas仅用于生成OpenAPI文档
• 路由注册时，Fastify会单独校验Schema，不会自动读取Swagger配置中的定义，所以直接用$ref: '#/definitions/item'会找不到引用

方案1：将生成的Schema注册到Fastify的Schema仓库 #

这是标准解决方式，让Fastify的校验器能识别自定义Schema：

1. 提取并注册生成的Schema
   在index.ts中，把ts-json-schema-generator生成的定义通过fastify.addSchema()注册到Fastify：

import { createGenerator } from 'ts-json-schema-generator';
import type { FastifyInstance } from 'fastify';

// 生成Item的Schema
const generator = createGenerator({
  path: './src/types/Item.ts',
  type: 'openapi3' // 推荐生成OpenAPI 3格式，对应components.schemas
});
const itemSchema = generator.createSchema('Item');

async function bootstrap(fastify: FastifyInstance) {
  // 给Schema设置唯一ID，方便路由引用
  fastify.addSchema({ $id: 'item', ...itemSchema });

  // 注册Swagger配置
  await fastify.register(require('@fastify/swagger'), {
    swagger: {
      info: { title: 'API Docs', version: '1.0.0' },
      components: {
        schemas: { item: itemSchema } // 对应OpenAPI 3的结构
      }
    }
  });

  // 注册路由
  await fastify.register(require('./routes'));
}

2. 路由中引用已注册的Schema
   在routes.ts里直接通过$id或者完整路径引用：

export async function itemRoutes(fastify: FastifyInstance) {
  fastify.get('/item/:id', {
    schema: {
      response: {
        200: { $ref: 'item' } // 直接用注册的$id，更简洁
        // 或者用OpenAPI 3的完整路径：$ref: '#/components/schemas/item'
      }
    },
    handler: async (req, reply) => {
      return { id: req.params.id, name: 'Sample Item' };
    }
  });
}

方案2：适配Swagger 2.x的definitions结构 #

如果坚持用Swagger 2.x的definitions，可以把definitions下的所有Schema批量注册到Fastify：

// index.ts中
const generatedSwaggerConfig = {
  swagger: {
    info: { title: 'API Docs', version: '1.0.0' },
    definitions: {
      item: generator.createSchema('Item'),
      // 其他定义...
    }
  }
};

// 批量注册definitions里的所有Schema
for (const [key, schema] of Object.entries(generatedSwaggerConfig.swagger.definitions)) {
  fastify.addSchema({ $id: key, ...schema });
}

// 注册Swagger
await fastify.register(require('@fastify/swagger'), generatedSwaggerConfig);

路由中同样用$ref: 'item'即可。

不推荐：忽略校验错误 #

如果不需要Fastify的Schema校验（不建议生产环境使用），可以给路由添加skipValidation: true跳过校验：

fastify.get('/item/:id', {
  schema: {
    response: {
      200: { $ref: '#/definitions/item' }
    }
  },
  skipValidation: true, // 跳过校验，不再报错
  handler: async (req, reply) => { /* ... */ }
});

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