Я следовал спецификации 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 работает неправильно. Любые советы приветствуются, спасибо.
example
(единственное число) не поддерживает$ref
и требует встроенного примера.$ref
может использоваться вexamples
(множественное число), но только для ссылки на весь пример, а не на его части. Если вы используете пользовательский интерфейс Swagger — имейте в виду, что в настоящее время он поддерживаетexample
, но неexamples
; поддержкаexamples
отслеживается на github.com/swagger-api/swagger-ui/ вопросы/2651. - person Helen   schedule 23.10.2018examples
не работает в моем редакторе Swagger. - person David Chen   schedule 23.10.2018