Валидатор OpenAPI и Swagger с просмотром спецификации

Проверка спецификации OpenAPI 3.0/3.1 и Swagger 2.0 (YAML и JSON) с номерами строк и документация в стиле Swagger UI.

Данные обрабатываются в браузере и никуда не отправляются

Ввод

Перетащите файл сюда или выберите на диске

Результат

Здесь появится результат

Введите данные слева - результат появится сразу

Как пользоваться

Вставьте спецификацию OpenAPI или Swagger в YAML либо JSON (или загрузите файл) - проверка и документация появляются сразу. Версия определяется по полю openapi или swagger: поддерживаются Swagger 2.0, OpenAPI 3.0 и 3.1. Спецификация проверяется по официальной схеме и по правилам, которые схема не ловит: параметры пути из адреса, повторяющиеся operationId, ссылки $ref в никуда, неиспользуемые схемы. Каждая ошибка показана по-русски с номером строки - по клику курсор переходит к ней.

Под ошибками выводится документация в духе Swagger UI: операции по тегам с параметрами, телом запроса и ответами, схемы данных деревом (allOf объединяется, oneOf и anyOf показаны вариантами, циклические ссылки помечены). Это только просмотр: никакие запросы к серверам из спецификации не отправляются, внешние ссылки не загружаются.

Частые ошибки

Вот что чаще всего ломается в спецификациях:

Параметр пути не описан

Если в адресе есть {id}, в parameters должен быть параметр с in: path, name: id и required: true. Без required: true спецификация недопустима, а генераторы клиентов и серверов дают сбой или молча подставляют не то.

Сломанная ссылка $ref

Опечатка в имени схемы (#/components/schemas/Usr вместо User) не видна глазами, но валидатор покажет её сразу. В Swagger 2.0 схемы лежат в #/definitions, в OpenAPI 3 - в #/components/schemas.

Повторяющийся operationId

operationId должен быть уникален во всей спецификации: по нему генераторы называют методы клиентов. Повтор приводит к конфликту имён в сгенерированном коде.

Код ответа в кавычках и без

В YAML код 200 без кавычек читается как число, а в OpenAPI это ключ-строка. Большинство инструментов это прощают, но надёжнее писать '200'. Допустимы также 2XX, 4XX и default.

Путаница между версиями

Поле nullable есть только в OpenAPI 3.0, в 3.1 вместо него type: [string, null]. Тело запроса в Swagger 2.0 - параметр in: body, в OpenAPI 3 - requestBody. Проверяйте, по какой схеме написана спецификация.

Опечатки в названиях полей

Лишнее поле вроде descripton молча игнорируется инструментами, но в схеме OpenAPI оно запрещено. Собственные поля нужно начинать с x-.

Частые вопросы

Отправляется ли моя спецификация на сервер?

Нет - 100%. Сайт целиком статический, у него нет серверной части. Проверка и построение документации выполняются в вашем браузере, а запросы к серверам из спецификации не отправляются.

Какие версии поддерживаются?

Swagger 2.0, OpenAPI 3.0.x и 3.1.x, формат YAML и JSON. Для более новых 3.x проверка выполняется по схеме 3.1 с предупреждением.

По каким правилам проверяется спецификация?

По официальным JSON-схемам OpenAPI Initiative (структура документа, обязательные поля, допустимые значения), плюс по дополнительным правилам: параметры пути, уникальность operationId, разрешимость $ref, объявленные схемы безопасности, неиспользуемые схемы.

Почему не загружаются внешние ссылки на другие файлы?

Сайт ничего не скачивает и не отправляет. Ссылки на другие файлы (./common.yaml#/Item) и адреса http не раскрываются: соберите спецификацию в один файл (например, командой swagger-cli bundle или redocly bundle) и вставьте результат.

Чем это отличается от Swagger Editor и Swagger UI?

Здесь нет кнопки «Try it out» и отправки запросов - только проверка и просмотр. Зато всё работает офлайн-подобно, быстро и без передачи данных, а ошибки показаны по-русски с номерами строк.

Что значит предупреждение, а не ошибка?

Предупреждение - спецификация допустима, но есть неудобство: не указан список servers, есть неиспользуемые схемы, у операции нет успешного ответа, у операций нет summary и т. п. Ошибка - нарушение стандарта.

Как проверить данные по схеме из спецификации?

Скопируйте нужную схему из components.schemas в валидатор JSON Schema нашего каталога и проверьте по ней пример тела запроса или ответа.

Курс «Проектирование архитектуры и интеграций (API, брокеры) + ИИ»

REST, gRPC, SOAP, GraphQL и JSON-RPC, архитектурные подходы, SQL и NoSQL, брокеры сообщений и работа с ИИ. Программа курса помогает систематизировать знания об API и интеграциях; содержание и условия обучения смотрите на Stepik.

Перейти к курсу на Stepik