大量使用示例，显示奇怪的$$ ref元素

Question

我写了一个摇摇欲坠的Yaml文件，在components部分中，我有：

examples:
  companyExample:
    company:
      id: uNiquEiD
      name: Company Name

我在响应中使用此companyExample如下：

example:
  $ref: '#/components/examples/companyExample'

以下是输出：

那么这个额外的"$$ref": "#/components/examples/companyExample"是什么错误？如何删除它？

Answer 1

example关键字（不要与多个exampleS混淆）不支持$ref。整个示例值必须内联指定：

example:
  company:
    id: uNiquEiD
    name: Company Name

要$ref中定义的示例，您需要使用#/components/examples关键字。 examples可以在参数，请求主体，响应主体和响应头中使用，但不能在模式中使用。换句话说，可以使用examples 沿着 examples，而不是内部 schema。

例如，以schema作为响应示例，您将使用以下示例。请注意，示例定义使用value关键字来包装实际示例值。 （由于缺少$ref，因此原始问题中的示例定义无效。）

value

Swagger UI用户注意： responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Company' examples: companyExample: $ref: '#/components/examples/companyExample' components: examples: companyExample: summary: Sample company data value: # The actual example value begins here company: id: uNiquEiD name: Company Name 的呈现尚未实现。按照this issue进行更新。