OpenAPI3の`#/components/examples/`で定義したexampleは`'#/components/schemas/`で`$ref`できない

タイトルままなのだけれど、OpenAPI3の#/components/examples/で定義したexampleは'#/components/schemas/で$refできません。 APIのレスポンスボディの例として使おうとして気づきました。

NGパターン

OpenAPIで、#/components/examples/に例を定義して、'#/components/schemas/で定義したスキーマオブジェクトで参照してみます。以下のようなyaml。

openapi: "3.0.3"
info:
  title: sample
  description: "`hoge"
  version: "1.0.0"
servers:
  - url: http://example.com/api
paths:
  /user:
    post:
      description: create user
      responses:
        '201':
          description: created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
components:
  schemas: 
    User:
      type: object 
      required: 
        - id
      properties:
        id: 
          type: integer 
          format: int64 
        name:
          type: string
      example:
        $ref: '#/components/examples/UserExample'
  examples:
    UserExample:
      value:
        id: 1
        name: John

このyamlをSwagger Editorで表示すると、エラーは出力されないものの、exampleの表示は$ref: '#/components/examples/UserExampleになって意図したオブジェクトが表示されません。下記のようなイメージ。

スキーマのexample表示もなにかがおかしい

OKパターン

色々試したんですが、APIのレスポンスボディとして#/components/examples/に定義した例を使いたい場合は、Media Type Objectのexamplesフィールドで参照するとうまくいきます。

openapi: "3.0.3"
info:
  title: sample
  description: "`hoge"
  version: "1.0.0"
servers:
  - url: http://example.com/api
paths:
  /user:
    post:
      description: Returns all pets from the system that the user has access to
      responses:
        '201':
          description: create user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
              examples:
                User:
                  $ref: '#/components/examples/UserExample'
components:
  schemas: 
    User:
      type: object 
      required: 
        - id
      properties:
        id: 
          type: integer 
          format: int64 
        name:
          type: string
      example:
        id: 2
        name: Bob
  examples:
    UserExample:
      value:
        id: 1
        name: John

上記のように書くと、以下のようにちゃんと表示してくれます。

それもそのはずで、OpenAPIの仕様をちゃんと読むと、exampleフィールドとexamplesフィールドって明確に区別されてるのです。

例えば、Schema Objectなどにあるexampleフィールドの型はAnyでフリーフォーマットな記載が可能なものです。

一方で、#/components/examples/はExample Object を定義しているので、このObjectが利用可能なフィールドでだけ参照することができます。

仕様をちゃんと読まずに、しょうもないことに時間を使ってしまいまいた。英語力が欲しい。