Swagger重用示例显示奇怪的$$ ref元素

Question

我写了一个swagger规范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内使用。

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

      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

Swagger UI用户请注意：examples的渲染尚未实现。关注this issue更新。