使用Ajv验证OpenAPI组件Schema时$ref引用报错求助

在使用Ajv加载包含$ref引用的OpenAPI YAML Schema时持续报错，相关代码如下：

YAML文件内容 #

openapi: 3.0.3
info:
  title: Demo
  version: 1.0.0
paths:
  /carousel:
    get:
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/test"
components:
  schemas:
    other:
      type: object
      properties:
        component:
          type: object
    test:
      type: object
      properties:
        slides:
          type: array
          items:
            type: object
            properties:
              contents:
                type: array
                items:
                  anyOf:
                    - $ref: "#/components/schemas/other"

尝试的JS + Vite代码 #

第一种写法：

import Ajv from 'ajv'
import YamlContent from '../Config/API.yaml'; // vite.config.js 配置了 @modyfi/vite-plugin-yaml
const validate =
  new Ajv({
    schemas: YamlContent.components.schemas
  }).
  getSchema(YamlContent.components.schemas.test);

第二种写法：

const validate =
  new Ajv().
  addSchema(YamlContent.components.schemas.other).
  compile(YamlContent.components.schemas.test);

两种写法均报错，请问问题出在哪？

问题核心在于**$ref路径匹配规则和Schema的标识注册逻辑**：

1. 根本原因
   你使用的$ref是基于完整OpenAPI文档的绝对路径（#/components/schemas/other），但Ajv无法识别该路径——因为你既没有将整个OpenAPI文档作为根Schema传入，也没有给单个Schema注册对应的$id来匹配引用路径。

2. 可行解决方法
   有两种直接有效的方案：

   • 方案一：给Schema添加$id属性
     修改YAML中的schemas部分，为每个schema添加与$ref路径一致的$id：

     components:
       schemas:
         other:
           $id: "#/components/schemas/other"
           type: object
           properties:
             component:
               type: object
         test:
           $id: "#/components/schemas/test"
           type: object
           properties:
             slides:
               type: array
               items:
                 type: object
                 properties:
                   contents:
                     type: array
                     items:
                       anyOf:
                         - $ref: "#/components/schemas/other"
     

     然后在代码中遍历注册所有Schema：

     import Ajv from 'ajv'
     import YamlContent from '../Config/API.yaml';
     
     const ajv = new Ajv();
     // 遍历所有schema，Ajv会自动识别$id并匹配$ref
     Object.values(YamlContent.components.schemas).forEach(schema => ajv.addSchema(schema));
     // 通过$id路径获取验证函数
     const validate = ajv.getSchema("#/components/schemas/test");
     

   • 方案二：传入完整OpenAPI文档作为根Schema
     无需修改YAML，直接将整个OpenAPI文档添加到Ajv实例，再通过完整路径获取Schema：

     import Ajv from 'ajv'
     import YamlContent from '../Config/API.yaml';
     
     const ajv = new Ajv();
     // 将整个OpenAPI文档注册为一个Schema，可自定义标识名
     ajv.addSchema(YamlContent, 'openapi-doc');
     // 通过完整的$ref路径获取验证函数
     const validate = ajv.getSchema("#/components/schemas/test");
     

3. 之前写法失败的原因

   • 第一种写法中，schemas选项传入的是Schema对象集合，但Ajv不会自动给这些Schema绑定#/components/schemas/xxx的标识，导致$ref无法匹配。
   • 第二种写法中，仅添加了otherSchema，但未给它注册对应#/components/schemas/other的标识，test中的$ref路径依然无法被Ajv识别。

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