Разрешен ли $ref в info.description в документах OpenAPI 3.0/3.1?
Быстрый старт Redocly имеет следующее:
info:
description:
$ref: ./info-description.md
Запуск интерфейса командной строки Redocly работает правильно с этим определением. Точно так же работает «redocly lint». Однако Visual Studio жалуется, что значение description должно быть строкой,
и действительно, спецификация соответствует. В документации Swagger также отмечается, что $ref недоступен нигде (но не дает очень много информации о том, где именно это разрешено).
Кажется маловероятным, что Redocly, как один из основных инструментов в мире OpenAPI, нарушил бы стандарт в своем собственном каноническом примере того, как использовать стандарт. Это проблема с Redocly, Visual Studio или чем-то еще? Если это использование правильно, есть ли способ заставить Visual Studio прекратить работу?
Ответы 1
Вы правы, info.description должна быть строкой — $ref не везде поддерживается в спецификации OpenAPI, хотя не всегда понятно, где она есть и не поддерживается. Redocly попытается разрешить $ref, где бы он ни находился, поскольку ясно, что имел в виду пользователь. Некоторые другие инструменты делают то же самое, но, как вы обнаружили, не все; Я думаю, что в этом случае инструмент Visual Studio является правильным.
Спасибо за быстрый ответ. Логически, я думаю, Редокли все правильно понял. Я не вижу логической причины для исключения этого здесь. Но стандарт есть стандарт, я полагаю.
Ну, это неловко. Привет, я работаю в Redocly, и я собираюсь внести некоторые изменения в наш пример проекта! (а также ответ на ваш актуальный вопрос)