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

Question

我写了一个 swagger 规范 Yaml 文件，在 components 部分我有：

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

我在回复中使用这个 companyExample 如下：

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

这是输出：

那么这个额外的内容是什么 "$$ref": "#/components/examples/companyExample" 是 bug 吗？我怎样才能删除它？

Answer 1

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

example:
  company:
    id: uNiquEiD
    name: Company Name

要 $ref 在 #/components/examples 中定义的示例，您需要使用 examples 关键字。 examples 可用于参数、请求正文、响应正文和响应 headers 但不能用于模式。换句话说，可以使用 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 用户注意事项： Swagger UI 3.23.0+ 和 Swagger Editor 3.6 支持多个 examples .31+.

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

Swagger reusing examples showing weird $$ref element

swagger

swagger-ui