Redocly OpenAPI结构错误：$ref引用文件含非法顶层属性

错误原因 #

你在根文件openapi.yaml的单个路径节点（/kpiDocumentation）下，通过$ref引用了一个完整的OpenAPI文档（kpi-documentation.yaml），但该位置仅允许存放单一路径的操作定义（如get/post、参数、响应等），不允许出现openapi、info、paths这类顶层OpenAPI字段，因此Redocly会抛出结构错误。

而单独预览kpi-documentation.yaml正常，是因为它本身是一个符合规范的完整OpenAPI文档，不存在结构问题。

两种修复方案 #

方案1：引用单一路径的操作定义 #

1. 修改kpi-documentation.yaml，移除所有顶层字段（openapi、info、servers、paths），仅保留目标路径的操作内容：

get:
  summary: Same as the Performance Ratio, but the ratio is done using Corrected Reference Yield, so it considers thermal losses in the panels as normal. The WCPR represents the losses in the BoS (balance of system), so everything from the panel DC output to the AC output. 
  operationId: corrected_performance_ratio_plants_retrieve
  parameters:
    - in: query
      name: date_end
      schema:
        type: string
        format: date
      required: true
  # 补充后续参数、响应定义

2. 调整根文件openapi.yaml的引用路径，匹配实际API路径：

paths:
  "/api/v1/corrected-performance-ratio/plants/{id}":
    $ref: paths/kpi-documentation.yaml

方案2：引用完整的paths集合 #

如果需要将多个路径定义统一放在kpi-documentation.yaml中，可按以下方式修改：

1. 修改kpi-documentation.yaml，仅保留paths节点下的所有路径定义，移除其他顶层字段：

"/api/v1/corrected-performance-ratio/plants/{id}":
  get:
    summary: Same as the Performance Ratio...
    operationId: corrected_performance_ratio_plants_retrieve
    parameters:
      - in: query
        name: date_end
        schema:
          type: string
          format: date
        required: true
    # 补充后续内容
# 可添加更多路径定义

2. 在根文件openapi.yaml的paths节点直接引用该文件：

paths:
  $ref: paths/kpi-documentation.yaml

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