Как правильно ссылаться на пример в компонентах (OAS 3.0)

Я следовал спецификации OAS 3.0. чтобы написать свой документ в YAML, но результат, отображаемый редактором Swagger, искажен.

Объект responses под некоторым объектом operation

  responses:
    200:
      description: "..."
      content:
        application/json:
          schema:
            $ref: '...'
          example:
            $ref: '#/components/examples/person'

example, на который я хочу сослаться

components:
  examples:
    person:
      value:
        name: "Joe"
        description: "I am a programmer"

Что я вижу в правой части редактора Swagger (рендеринг результата)

{
  "value": {
    "name": "Joe",
    "description": "I am a programmer"
  },
  "$$ref": "#/components/examples/person"
}

Что я ожидал

{
    "name": "Joe",
    "description": "I am a programmer"
}

Я попытался добавить value к оператору ссылки,

$ref: '#/components/examples/person/value'

и вот что я получил.

{
  "name": "Joe",
  "description": "I am a programmer",
  "$$ref": "#/components/examples/person/value"
}

Я чувствую, что это неправильный путь, потому что добавление value к каждому оператору ссылки кажется мне довольно странным, и тем не менее это не работает должным образом.

Я пытался гуглить, но большинство результатов не имеют значения. Мне интересно, неправильный ли мой синтаксис или редактор Swagger работает неправильно. Любые советы приветствуются, спасибо.


person David Chen    schedule 23.10.2018    source источник
comment
Подытожим связанные вопросы и ответы ^^: example (единственное число) не поддерживает $ref и требует встроенного примера. $ref может использоваться в examples (множественное число), но только для ссылки на весь пример, а не на его части. Если вы используете пользовательский интерфейс Swagger — имейте в виду, что в настоящее время он поддерживает example, но не examples; поддержка examples отслеживается на github.com/swagger-api/swagger-ui/ вопросы/2651.   -  person Helen    schedule 23.10.2018
comment
@Helen Большое спасибо! Это помогает прояснить мое замешательство, почему использование examples не работает в моем редакторе Swagger.   -  person David Chen    schedule 23.10.2018