在 OpenAPI 3 的 #/components/schemas 顶层 `$ref`-ing 多个文件

Question

在我的 API 中，我有很多数据结构（模型），将它们组织到单独的文件中会很有帮助。比如我有文件widgets.a.yaml:

WidgetA1:
  # schema def
WidgetA2:
  # schema def

还有widgets.b.yaml中的另一个defs集合：

WidgetB1:
  # schema def
WidgetB2:
  # schema def

现在在我的主要 OpenAPI 定义中，如果我这样做：

# ...
# other OpenAPI def stuff
# ...
components:
  schemas:
    { $ref: widgets.a.yaml }

... OpenAPI 文档构建并生成了一些可爱的文档仅限 A 类小部件。

如果我尝试像这样引用这两个文件：

# ...
# ther OpenAPI def stuff
# ...
components:
  schemas:
    { $ref: widgets.a.yaml }
    { $ref: widgets.b.yaml }

... Swagger 工具链抛出一个错误，指出 schemas 中存在重复键，但两个 widgets.(a|b).yaml 文件是互斥的（即没有共享架构定义）。

有没有人有关于将大型数据模型组织成多个文件（每个文件可能有多个 JSON Schema 架构）的技巧？

与此相关，如果有某种方法可以在 OpenAPI 文档的 #/components/schemas 部分中“嵌套”模型，我会真的更喜欢......例如指的是像#/components/schemas/widgets.a/WidgetA1 这样的小部件。然而，OpenAPI 文档的#/components/schemas 部分似乎是“扁平的”（即扁平命名空间），并且所有模型都必须在该列表中具有“全局”唯一键......这是真的吗？我可以找到有关组织纯 JSON Schema 项目的各种方法的文档，但是想要使用 Swagger 进行文档意味着需要符合 OpenAPI，并且在这些 API 规范中似乎没有很多已建立的用于组织大型数据模型的模式。 （这里的“大”是指数百个类/模型。）

Answer 1

在 OpenAPI 中，您只能引用单个架构。这意味着您需要重新定义 components/schemas 部分中的架构名称，并将每个名称指向相应的架构定义：

components:
  schemas:
    WidgetA1:
      $ref: widgets.a.yaml#/WidgetA1
    WidgetA2:
      $ref: widgets.a.yaml#/WidgetA2
    WidgetB1:
      $ref: widgets.b.yaml#/WidgetB1
    ...

不支持直接在components/schemas下“导入”整个文件，即以下内容无效：

components:
  schemas:
    $ref: widgets.a.yaml

所有模型都必须在该列表中具有“全局”唯一键...是这样吗？

是的。

如果在 OpenAPI 文档的 #/components/schemas 部分中有某种“嵌套”模型的方法，我会真的甚至更喜欢......例如指的是像#/components/schemas/widgets.a/WidgetA1 这样的小部件。

没有架构命名空间的概念，但您可以通过在架构名称中使用点来模拟它们，例如MyNamespace.WidgetA1.

components:
  schemas:
    MyNamespace1.WidgetA1:
      ...
    AnotherNamespace.WidgetB2:
      ...