OpenAPI 3+与Redoc多级嵌套引用失效问题求助

你遇到的问题不是OpenAPI或Redoc不支持多级深度引用，而是误解了components.schemas的结构规则：

• OpenAPI的components.schemas是一个扁平的键值集合，每个键对应一个独立的Schema定义，并不支持嵌套的命名空间结构。
• 当你在_index.yaml中写admin: $ref: "./admin/_index.yaml"时，你实际是定义了一个名为admin的Schema，这个Schema的内容是./admin/_index.yaml里的Participants属性结构，而不是创建了一个名为admin的命名空间，里面包含Participants这个子Schema。

这就是为什么#/components/schemas/admin/Participants会报错——这个引用路径指向的是admin Schema的Participants属性，而不是一个独立的Schema；而#/components/schemas/AdminParticipants能正常工作，是因为它直接指向一个顶级的Schema键。

正确的多级Schema组织方式 #

如果你想按admin分类组织Schema，有两种可行方案：

方案1：使用带前缀的Schema名称（推荐） #

直接在Schema名称中加入分类前缀，保持schemas结构扁平：
比如在components/schemas/admin/_index.yaml中定义：

AdminParticipants:
  $ref: ./Participants.yaml

然后在_index.yaml中引用：

$ref: ./admin/_index.yaml

这样所有admin相关的Schema都会以Admin为前缀出现在schemas顶级，引用时直接用#/components/schemas/AdminParticipants即可。

方案2：将分类作为Schema的属性（不推荐用于独立Schema引用） #

如果一定要保留嵌套结构，只能把admin作为一个包含多个属性的Schema，但此时Participants只是这个Schema的属性，而非独立Schema：
修改components/schemas/admin/_index.yaml为：

type: object
properties:
  Participants:
    $ref: ./Participants.yaml

然后在_index.yaml中：

admin:
  $ref: ./admin/_index.yaml

此时引用admin Schema的Participants属性时，路径应为#/components/schemas/admin/properties/Participants，但这种方式下Participants无法作为独立Schema被其他地方直接引用，只适合作为admin Schema的一部分。

总结 #

OpenAPI并不支持通过嵌套命名空间的方式组织components下的Schema/参数等资源，所有资源都必须是对应components子节点下的顶级键。你需要通过命名前缀来实现分类，而非嵌套结构。

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