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 Swagger UI 3.23.0+ 和 Swagger Editor 3.6.31+ 中提供了对多个的支持。