Как пользоваться: Валидатор OpenAPI / Swagger
- Вставьте содержимое
openapi.yaml/swagger.jsonили откройте файл. - Версия (OpenAPI 3.1, 3.0 или Swagger 2.0) определяется автоматически.
- Сначала исправьте ошибки схемы — каждая указывает на место в документе.
- Проверьте дополнительные проверки и список эндпоинтов.
Что проверяется
| Проверка | Подробности |
|---|---|
| Официальная схема | Документ проверяется по JSON Schema инициативы OpenAPI Initiative для его версии (3.1, 3.0 или Swagger 2.0): обязательные поля, допустимые ключи, типы значений |
Битый $ref | Каждая локальная ссылка (#/components/schemas/Pet) должна указывать на существующий объект |
Уникальный operationId | Дубликаты ломают генераторы SDK и ссылки в документации |
| Параметры пути | Каждый {param} в пути должен быть объявлен с in: path и required: true, и наоборот |
| Ответы | Каждая операция должна иметь как минимум один ответ |
| Подсказки | Отсутствующие operationId, servers или info.description |
Версии OpenAPI
- Swagger 2.0 —
swagger: "2.0",definitions,host/basePath. - OpenAPI 3.0 —
components,servers,requestBody; схемы представляют собой подмножество JSON Schema draft-04 сnullable. - OpenAPI 3.1 — полностью соответствует JSON Schema 2020-12 (вместо
nullableиспользуетсяtype: [string, "null"]), добавленыwebhooks.
Ограничения
Внешние ссылки на другие файлы или URL не загружаются — сначала объедините спецификации из нескольких файлов, например с помощью redocly bundle. Проверка схемы выявляет структурные проблемы; стилевые правила, например соглашения об именовании, требуют линтера вроде Spectral. Проверить примеры данных по вашим схемам можно с помощью валидатора JSON Schema, синтаксис YAML — с помощью валидатора YAML, а работающий API — с помощью тестировщика API.
Также ищут как: валидатор swagger, валидатор openapi, проверка openapi, валидатор openapi 3.1, валидатор swagger 2.0, openapi lint, проверка api spec.
Инструменты, которые хорошо сочетаются с Валидатор OpenAPI / Swagger
- JSON форматтер — Вставьте JSON, чтобы отформатировать, минифицировать или проверить его.
- cURL в код — Вставьте команду curl из документации к API или пункт «Copy as cURL» из DevTools браузера, и вы получите готовый код для шести языков с сохранёнными заголовками, телом запроса и авторизацией.
- Тестер JSONPath — Введите запрос JSONPath и сразу увидите, что он выбирает, с точным путём каждого совпадения.
- JSON в YAML — Вставьте JSON и получите аккуратный YAML для манифестов Kubernetes, Docker Compose, GitHub Actions или любого конфигурационного файла.
Часто задаваемые вопросы
Поддерживается ли OpenAPI 3.1?
Да — OpenAPI 3.1.x, 3.0.x и Swagger 2.0 проверяются по своим официальным схемам.
Почему одна ошибка даёт так много сообщений?
Официальные схемы используют альтернативы (oneOf), поэтому одно неверное значение может провалить сразу несколько веток. Инструмент отфильтровывает их и оставляет самые конкретные сообщения; исправьте первое из них и проверьте заново.
Может ли инструмент следовать $ref на другие файлы?
Нет, только на ссылки внутри того же документа. Сначала объедините спецификации из нескольких файлов в один.
Загружается ли моя спецификация API на сервер?
Нет. Проверка выполняется полностью в вашем браузере, поэтому внутренние API-решения остаются приватными.
Можно ли установить Валидатор OpenAPI / Swagger как веб-приложение и пользоваться им офлайн?
Да. Валидатор OpenAPI / Swagger — это веб-приложение (PWA), которое можно установить из браузера, без скачивания из магазина приложений. В Chrome или Edge (Windows, macOS, Linux, ChromeOS) или на Android нажмите вверху этой страницы «Установить приложение»; на iPhone и iPad используйте «Поделиться → На экран «Домой»», а в Safari 17+ на Mac — «Файл → Добавить в Dock». После этого приложение откроется в отдельном окне со своим значком, и так как оно полностью работает в браузере, оно продолжит работать офлайн. Firefox на компьютере не умеет устанавливать веб-приложения. Как работает установка.