Fastify路由中使用Swagger $ref提示找不到引用的问题咨询

你的错误核心是**$ref的格式不符合OpenAPI规范**，直接写Data无法让Fastify定位到正确的Schema定义，同时需确保路由能正确访问全局的components schema。以下是具体修正方案：

1. 修正$ref的引用路径 #

OpenAPI规范要求$ref必须使用完整的JSON Pointer格式，指向components/schemas下的目标Schema，正确写法为：

$ref: '#/components/schemas/Data'

注意：路径开头的#是必填项，代表当前OpenAPI文档的根节点。

2. 修正后的完整代码 #

await app.register(swagger, {
    openapi: {
        openapi: '3.1.0',
        info: {
            version: '1.0.0',
            title: 'Example app',
        },
        components: {
            schemas: {
                Data: {
                    type: 'object',
                    properties: {
                        name: { type: 'string' },
                    }
                },
            }
        }
    }
});

// 无需嵌套额外的register，直接注册路由即可（拆分插件时确保在Swagger注册后加载）
app.get('/route', {
    schema: {
        response: {
            200: {
                $ref: '#/components/schemas/Data'
                // 注意：无需重复声明type: 'object'，Schema本身已定义类型
            }
        }
    }
}, (request: FastifyRequest, reply: FastifyReply) => {
    return reply.status(200).send({ 'name': 'Works' });
});

关键说明 #

• 移除冗余定义：Data Schema已声明type: 'object'，路由的response配置里无需重复写，否则可能引发格式冲突。
• 插件加载顺序：确保Swagger插件先于路由注册（你的代码已满足此要求），拆分路由到独立插件时，需保证该插件在Swagger插件之后加载。
• 单一数据源（SSOT）：通过#/components/schemas/Data复用Schema，所有路由均可引用同一定义，修改Schema时只需更新components中的内容即可。

修改后，Fastify能正确识别Schema定义，Swagger UI也会自动关联路由与对应的Schema，满足你所需的复用和关联需求。

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