使用Redocly构建API文档时为何出现“Invalid JSON pointer”错误？

问题根源 #

报错Invalid JSON pointer: components/schemas/agreement_schema.yaml#/NewAgreement的核心原因是外部Schema引用格式不符合OpenAPI规范和Redocly的解析要求。你当前的$ref写法混淆了Schema组件路径与外部文件路径，导致Redocly无法正确识别JSON指针。

具体修复步骤 #

1. 修正主OpenAPI文件的$ref引用格式
   引用外部Schema文件时，必须使用相对文件路径搭配JSON指针，而非将文件名嵌套在components/schemas路径下。
   错误写法示例：

   $ref: 'components/schemas/agreement_schema.yaml#/NewAgreement'
   

   正确写法（假设主文件在openapi/目录，agreement_schema.yaml在openapi/components/schemas/目录）：

   $ref: './components/schemas/agreement_schema.yaml#/NewAgreement'
   

2. 校验外部Schema文件结构
   确认agreement_schema.yaml中NewAgreementSchema的定义层级：

   • 如果Schema直接定义在文件根节点，结构应为：

     type: object
     properties:
       id:
         type: string
       content:
         type: string
     

   • 如果文件包含多个Schema，需用components/schemas包裹，此时引用路径要对应调整：

     # agreement_schema.yaml 内容
     components:
       schemas:
         NewAgreement:
           type: object
           properties:
             # 字段定义
     

     对应引用写法：

     $ref: './components/schemas/agreement_schema.yaml#/components/schemas/NewAgreement'
     

3. 重新执行构建命令
   修正引用后，再次运行：

   redocly build-docs openapi/openapi.yaml
   

额外验证点 #

• 核对文件路径大小写（Linux/macOS环境下路径区分大小写）
• 确保Redocly CLI为最新版本，可通过以下命令升级：

  npm update -g @redocly/cli
  

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