Softonic

Онлайн-валидатор спецификаций OpenAPI

Шаг 1 / 2
Далее

Вставьте свою спецификацию OpenAPI или Swagger выше, чтобы получить список ошибок и предупреждений. Эта страница объясняет, что означает каждое сообщение и как его исправить, чтобы быстро перейти от красного отчёта к чистому. Ошибки делают документ недействительным, предупреждения, нет.

Как проверить спецификацию и работать с отчётом

  1. 1

    Вставьте спецификацию

    Вставьте документ в формате JSON или YAML в поле.

  2. 2

    Откройте результаты

    Перейдите к шагу результатов, чтобы увидеть либо сообщение о корректности, либо список ошибок.

  3. 3

    Найдите каждое сообщение

    Найдите сообщение в таблице ниже и внесите исправление в исходный файл.

  4. 4

    Вставьте снова

    Повторяйте проверку, пока не останется ошибок, а затем решите, какие предупреждения стоит исправить.

Как читать сообщения об ошибках

Сообщение Значение Исправление
Could not parse as JSON or YAML. Текст нельзя прочитать ни в одном из форматов Исправьте синтаксис: лишние запятые, неверные отступы, незакрытые скобки
Missing ‘openapi’ or ‘swagger’ version field. Нет ключа версии на верхнем уровне Добавьте openapi: 3.0.3 или swagger: "2.0"
Missing ‘info’ object. Нет раздела info Добавьте info с title и version
info.title is required. В info нет title Добавьте title в info
info.version is required. В info нет version Добавьте version в info (версию вашего API)
Missing ‘paths’ object. Нет раздела paths Добавьте paths, даже пустой на первом этапе

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

Как читать предупреждения

Сообщение Значение Исправление
Path ‘x’ should start with ‘/’. Ключ в paths не начинается с косой черты Переименуйте в /x
Unknown method ‘x’ on /path. Ключ под путём отсутствует в списке известных методов Проверьте опечатку или игнорируйте, если это намеренное расширение или trace

Список известных ключей: get, post, put, patch, delete, head, options, parameters, summary, description и servers. Расширения вендора, начинающиеся с x-, в этот список не входят, поэтому они тоже выводятся как предупреждения.

Что онлайн-проверка не может сообщить

Отчёт охватывает только структуру. Он не переходит по ссылкам $ref, не проверяет определения схем и не отмечает отсутствие значений operationId. Считайте успешную проверку подтверждением того, что файл имеет форму документа OpenAPI, а перед публикацией документации или генерацией клиентского кода используйте полноценный линтер.

Советы по работе с длинным отчётом

Начинайте с верха: ошибка разбора делает все остальные результаты ненадёжными, поэтому исправьте её в первую очередь. Затем займитесь отсутствующими полями верхнего уровня, потому что их быстро добавить. Только после этого смотрите предупреждения о путях. После каждого раунда правок вставляйте весь файл, а не фрагмент, поскольку проверкам нужен полный документ, чтобы найти info и paths. Отчёт без ошибок и с несколькими намеренными предупреждениями, нормальный и приемлемый конечный результат.

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

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

Не обязательно. Это значит, что структура верхнего уровня на месте. Схемы, ссылки и ответы не проверяются.

Ключи под путём сравниваются с фиксированным списком HTTP-методов и несколькими полями элемента пути. Ключ с префиксом x- в этот список не входит, поэтому он помечается как предупреждение. Его можно оставить.

Нет. Они идут в порядке проверок: сначала поле версии, затем info, затем paths. Номеров строк нет.

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

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

Создавайте до 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), свободно сочетая десятичные и двоичные единицы.

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

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