`$ref`-在OpenAPI 3中的#/components/schemas顶级位置上设置多个文件

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 }

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

与此相关的是，我甚至更喜欢在OpenAPI文档的#/components/schemas部分“嵌套”模型...例如，引用像#/components/schemas/widgets.a/widgeta1这样的小部件。但是，OpenAPI文档的#/components/schemas部分似乎是“平坦的”（即平坦的命名空间），并且所有模型在该列表中必须有一个“全局的”唯一键...是真的吗？我可以找到关于组织纯JSON模式项目的各种方法的文档，但是想要使用Swagger进行文档说明需要遵守OpenAPI，而且在这些API规范中似乎没有很多组织大型数据模型的既定模式。（这里的“large”表示数百个类/型号。）

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:
    $ref: widgets.a.yaml

所有模型在列表中必须有一个“全局”唯一的键...是真的吗？

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