OpenAPI：您可以在示例中使用子组件吗？

Question

OpenAPI 版本：3.0.1。

我正在研究 OpenAPI 规范的示例部分。

我熟悉组件，并且我知道我可以定义要在根级别使用的示例组件。 例如：

...
  examples:
    Students:
      $ref: '#/components/examples/students'

然而，在我的情况下，我只使用一个端点，它可能会在响应中提供大量不同的内容。 因此，我正在处理几个不同的示例，而为一个完整示例创建一个组件对我来说毫无用处。

另一方面，我在几个示例中重用了子部分，我想基于这些子部分创建组件。

类似于这个简化示例，其中我有一个具有相同教师和邮政地址的学生列表：

...
  examples:
    Students:
      value:
        - name: James Bond
          teacher: 
            $ref: '#/components/examples/teacherTrunchbull'
          postalAddress:
            $ref: '#/components/examples/london'
        - name: Bilbo Baggins
          teacher: 
            $ref: '#/components/examples/teacherTrunchbull'
          postalAddress:
            $ref: '#/components/examples/london'
        -  .......
...
components:
  examples:
    teacherTrunchbull:
      (value: ??)
        name: Agatha Trunchbull
        address: School street 34
        postalAddress:
          number: 5201
          name: London 
    london:
      (value: ??)
        number: 5201
        name: London
      

作为记录，我确实知道示例需要包含“值”作为字段，但我所能做的就是创建一个完整的示例，而不是为我的示例创建子组件。

我确实怀疑 OpenAPI 版本是 3.0.1。不支持我的要求，在这种情况下，只有这个有效：

...
  examples:
    Students:
      $ref: '#/components/examples/students'
      

如果是这种情况，请确认，以便我们将其称为结案。 但如果我要问的问题确实存在，那我该怎么做呢？

非常感谢您的回答。

Answer 1

example 不支持以这种方式使用$ref。

来自this 错误线程：

我们在这里的意思（如果需要，可以进一步澄清）是 这里给出的值是示例的实际值。不应该是 通过工具进一步解析。所以文档或模拟服务应该 在进一步“使用”它们之前不要尝试解析 $ref。

背后的原因正是 $ref 的。我们分不清什么时候结束 用户希望将 $ref 用作已解析的引用以及何时使用 想将它用作文字值（这是一个非常有效的情况）。作为 因此，我们决定这些示例将是未解析的文字值。 目前，没有办法有可解析的例子，作为外部 示例也是文字值。