Softonic

Валидатор OpenAPI

Шаг 1 / 2
Далее

Вставьте документ OpenAPI или Swagger, в JSON или YAML, и этот валидатор проверит его основную структуру. Он подтверждает, что документ разбирается, что в нём есть поле версии openapi или swagger, объект info с заголовком и версией, а также объект paths, затем отмечает пути, не начинающиеся со слэша, и неизвестные методы HTTP. Это быстрая структурная проверка, а не полноценный валидатор JSON Schema.

Как проходит проверка

  1. 1

    Вставьте документ

    JSON или YAML для OpenAPI 2 (Swagger) или OpenAPI 3.

  2. 2

    Разберите его

    Валидатор разбирает документ как JSON, а при неудаче переходит к разбору YAML.

  3. 3

    Проверьте обязательные поля

    Он подтверждает поле версии `openapi` или `swagger`, объект `info` с `title` и `version`, а также объект `paths`.

  4. 4

    Просканируйте пути

    Каждый путь проверяется на ведущий слэш, а каждый ключ операции сверяется с известными методами HTTP.

  5. 5

    Прочитайте отчёт

    Ошибки блокируют валидность; предупреждения указывают на пути без ведущего слэша и неизвестные методы.

Что проверяет этот валидатор

Проверка Результат при неудаче
Документ разбирается как JSON или YAML Ошибка
Есть поле openapi или swagger Ошибка
Есть объект info Ошибка
Есть info.title Ошибка
Есть info.version Ошибка
Есть объект paths Ошибка
Каждый путь начинается с / Предупреждение
Ключи операций: известные методы HTTP Предупреждение

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

Что он не проверяет

Это структурная проверка, а не полноценный валидатор спецификации. Он не:

  • проверяет каждый узел по официальной JSON Schema для вашей версии;
  • разрешает ссылки $ref и не подтверждает существование компонентов, на которые они указывают;
  • проверяет, что параметры пути объявлены и используются согласованно;
  • проверяет наличие или уникальность значений operationId;
  • сообщает номера строк ошибок.

Для такой глубины запустите специализированный CLI-валидатор, например redocly lint, swagger-cli validate или spectral lint. Используйте этот инструмент для быстрой проверки перед тем, как зафиксировать или поделиться спецификацией.

Версии OpenAPI на практике

Версия Примечания
Swagger 2.0 По-прежнему широко используется; поле swagger: "2.0"
OpenAPI 3.0.x Самая распространённая линейка 3.x
OpenAPI 3.1.0 Согласован с JSON Schema 2020-12

Этот валидатор принимает либо поле openapi (3.x), либо поле swagger (2.0), поэтому все они проходят проверку версии.

Минимальный документ, который проходит

openapi: 3.0.3
info:
  title: Example API
  version: 1.0.0
paths:
  /users:
    get:
      summary: List users

Все обязательные поля присутствуют, единственный путь начинается со слэша, а get является известным методом, поэтому документ отмечается как структурно корректный.

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

Swagger был первоначальным названием спецификации; в 2015 году её передали Linux Foundation и, начиная с версии 3.0, переименовали в «OpenAPI». Сейчас «Swagger» обозначает инструменты (Swagger UI, Swagger Editor). Сама спецификация называется OpenAPI. Этот валидатор принимает и поле версии swagger (2.0), и openapi (3.x).

Нет. Он проверяет основную структуру: что документ разбирается, содержит поле версии, объект info с заголовком и версией и объект paths, и предупреждает о путях без ведущего слэша и неизвестных методах. Он не проверяет каждый узел по официальной JSON Schema. Для этого используйте redocly lint или spectral lint.

Нет. Он не переходит по ссылкам $ref и не проверяет существование компонентов, на которые они указывают. Для межфайловых ссылок сначала объедините документ инструментом вроде redocly bundle или swagger-cli bundle, а затем запустите полноценный валидатор.

Нет. Он проверяет только вставленный документ, а не работающий код. Он не может определить, действительно ли ваш API возвращает то, что описано в спецификации. Это делают инструменты контрактного тестирования, такие как Dredd или Schemathesis.

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

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

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

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

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

Валидатор XSD

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

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

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

Проверка телефонных номеров

Проверьте структуру номера по стране и получите регион, тип, форматы E.164, международный, национальный и RFC 3966.

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

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

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