Softonic

Валидатор OpenAPI YAML

Шаг 1 / 2
Далее

Вставьте свой openapi.yaml, и валидатор проверит элементы, которые нужны каждой спецификации: поле версии, объект info с title и version и объект paths. Он также предупреждает о ключах путей без косой черты в начале и о ключах операций, которые не распознаёт.

Как проверить файл OpenAPI YAML

  1. 1

    Скопируйте YAML

    Скопируйте весь текст `openapi.yaml` или `swagger.yaml`, сохранив отступы в точности как есть.

  2. 2

    Вставьте в поле

    Вставьте его в поле документа OpenAPI / Swagger. В YAML отступы, это структура, поэтому не переписывайте и не переформатируйте их.

  3. 3

    Запустите проверку

    Перейдите к шагу результатов и прочитайте ошибки и предупреждения.

  4. 4

    Исправьте и проверьте снова

    Исправьте каждый указанный элемент в файле, вставьте новую версию и запустите проверку заново.

Почему отступы влияют на результат

В YAML вложенность ключей определяет, какому объекту принадлежит поле. Если version стоит на одном уровне с info, а не на уровень ниже, документ по-прежнему является читаемым YAML, но info.version отсутствует, и проверка это сообщит. То же касается paths: если ключ пути по ошибке сдвинут под info, объект paths верхнего уровня пропадает.

Используйте пробелы, а не табуляцию, и выдерживайте постоянный шаг, например два пробела на уровень.

Пример

openapi: 3.0.3
info:
  title: Pets API
paths:
  /pets:
    get:
      summary: List pets

Поле версии, info.title и paths присутствуют, а /pets начинается с косой черты, и get, известный метод. Не хватает только одного: info.version. Отчёт выводит:

Результат Тип
info.version is required. Ошибка

Добавьте version: 1.0.0 под info с отступом в два пробела, и документ будет признан структурно корректным.

Держите документы простыми для надёжного чтения

Проверка лучше всего читает обычные отображения YAML: простые строки ключ: значение, вложенные с единообразными отступами. Если документ с расширенными возможностями YAML, такими как якоря или многострочные блоки, признаётся нечитаемым или показывает отсутствующие поля, попробуйте JSON-копию той же спецификации, чтобы понять, в содержимом проблема или в синтаксисе YAML.

Чистый результат подтверждает только каркас. Он не разрешает ссылки $ref и не проверяет схемы.

Практический порядок работы с YAML-спецификациями

Редактируйте небольшими шагами и проверяйте часто. После добавления нового пути или перемещения блока вставляйте файл снова, чтобы неверный отступ был замечен, пока изменение свежее. Если вы разделяете большую спецификацию на несколько файлов, вставляйте объединённую версию, потому что эта проверка читает только переданный ей текст и не загружает другие файлы. Копируйте из редактора, а не со страницы в браузере, поскольку веб-страницы могут заменять пробелы и кавычки похожими символами, которые меняют способ чтения YAML.

Помните, что отчёт охватывает только то, что проверка может увидеть. Чистый результат для YAML-файла означает, что каркас верхнего уровня верен, но не то, что каждая операция, схема или ссылка внутри него верны.

Часто задаваемые вопросы

Пробелы. YAML не принимает табуляцию для отступов, а табуляция может сделать документ нечитаемым или сместить поля на другой уровень.

Обычно поле имеет неверный отступ и относится к другому объекту, чем вы задумали. Сравните его отступ с отступом родительского ключа.

Эта проверка смотрит только на наличие поля openapi или swagger, а не на его значение, поэтому версии в кавычках и без них проходят проверку. Заключать "2.0" в кавычки для Swagger всё равно полезная привычка.

Да. Документ сначала читается как JSON, а если это не удаётся, то как YAML, поэтому оба формата работают в одном поле.

Сопутствующие инструменты

Генератор вымышленных телефонных номеров

Создавайте до 50 вымышленных номеров из официально зарезервированных диапазонов пяти стран.

Генератор конфигурации webpack

Создайте webpack.config.js для webpack 5 под чистый JavaScript, React или Vue: TypeScript, Babel, CSS или Sass, изображения, HtmlWebpackPlugin, dev-сервер и команда npm install.

Генератор случайных букв

Генерируйте случайные буквы A-Z. Выберите количество, верхний или нижний регистр либо смешанный вариант для игр, заданий и уроков.

Валидатор XSD

Проверьте XML-документ в соответствии с схемой XSD и выявите несоответствия между элементами и их типами, указав точные номера строк.

Генератор случайных адресов

Создавайте 1–20 похожих на адрес записей для макетов и тестов в трёх упрощённых форматах.

Конвертер размера файлов

Преобразуйте значения между байтами, КБ, МБ, ГБ, ТБ и двоичными единицами IEC (KiB, MiB, GiB, TiB), свободно сочетая десятичные и двоичные единицы.

Инструмент доступен на других языках

Руководства и сценарии использования