Softonic

Валидатор OpenAPI 3.1

Шаг 1 / 2
Далее

Вставьте документ OpenAPI 3.1 в формате JSON или YAML, чтобы проверить его верхнеуровневую структуру. Инструмент ищет поле openapi, объект info с title и version и объект paths. Это структурная проверка, поэтому ключевые слова схем 3.1 она не валидирует, а некоторые шаблоны, удобные для 3.1, могут дать предупреждение или ошибку, о которых стоит знать.

Как проверить документ 3.1

  1. 1

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

    Вставьте документ со значением `openapi: 3.1.0` (или другим значением 3.1.x) в поле, в формате JSON или YAML.

  2. 2

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

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

  3. 3

    Прочитайте примечания для 3.1

    Проверьте, является ли отмеченный элемент реальной ошибкой или одним из шаблонов 3.1, описанных ниже.

  4. 4

    Дополните полноценным линтером

    Когда структура в порядке, используйте полный валидатор правил JSON Schema 2020-12.

Что инструмент делает с файлами 3.1

Версия 3.1 приводит схемы в соответствие с JSON Schema 2020-12. Этот валидатор не заглядывает внутрь схем вообще. Он проверяет только верхний уровень и записи путей, поэтому возможности схем 3.1, например массивы типов или const, здесь не проходят и не падают. Само значение версии также не проверяется: любое поле openapi считается присутствующим.

Два шаблона 3.1, на которые стоит обратить внимание

Шаблон в вашем файле 3.1 Что показывает инструмент
Объект webhooks и отсутствие объекта paths Ошибка: Missing ‘paths’ object.
Операция trace под путём Предупреждение: Unknown method ‘trace’ on the path
$ref как ключ элемента пути Предупреждение: Unknown method ‘$ref’ on the path

OpenAPI 3.1 позволяет описать документ только через webhooks, без paths. Этот инструмент требует paths, поэтому такой файл получает ошибку, хотя спецификация это допускает. Добавление пустого объекта paths: {} удовлетворяет проверку.

Список методов, который используется здесь: get, post, put, patch, delete, head, options, а также parameters, summary, description и servers. Метод trace есть в спецификации, но в этом списке его нет, поэтому он вызывает предупреждение, которое можно проигнорировать, если это сделано намеренно. Предупреждения не делают документ недействительным.

Пример

openapi: 3.1.0
info:
  title: Events API
  version: 2.0.0
webhooks:
  newEvent:
    post:
      summary: Event delivered

Результат: одна ошибка, “Missing ‘paths’ object.” Добавьте paths: {}, и структура пройдёт проверку.

Когда использовать это и когда идти дальше

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

Если предупреждение намеренное, например для trace, укажите это в pull request, чтобы рецензенты не задавались вопросом. Предупреждения никогда не меняют итог валидности, поэтому их можно оставить. Ошибки нужно устранить до того, как файл будет передан.

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

Нет. Он не заглядывает внутрь объектов схем, поэтому ключевые слова JSON Schema 2020-12 не проверяются. Он охватывает только верхнеуровневую структуру и записи путей.

Проверка требует объект paths. В файле 3.1 только с webhooks его нет, поэтому инструмент сообщает об отсутствии paths. Добавьте пустой paths: {}, чтобы пройти проверку.

Нет. Инструмент проверяет только наличие поля openapi или swagger, а не его значение.

Не обязательно. trace, допустимая операция в спецификации. Инструмент просто не включает её в список известных методов.

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

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

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

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

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