Валидатор OpenAPI: проверка API Spec

Что такое Валидатор OpenAPI?

Валидатор OpenAPI — это браузерный инструмент, который парсит и валидирует файлы спецификаций OpenAPI 3.x и Swagger 2.0. Вставьте JSON или YAML spec, нажмите Validate, и в течение секунд увидите, является ли spec структурно валидной, количество путей и операций, а также список предупреждений о недостающих полях, важных для генераторов SDK и инструментов документации.

Инструмент полностью работает в вашем браузере с использованием библиотеки @readme/openapi-parser, загружаемой по требованию. Никакое содержимое spec не отправляется на сервер. Бесплатный, без необходимости регистрации.

Используйте его перед коммитом spec в систему контроля версий, перед публикацией документации API или при отладке spec, которую отклоняет downstream-инструмент вроде Swagger UI, Stoplight или генератора SDK.

Основные возможности

• Поддержка OpenAPI 3.x и Swagger 2.0: Валидатор принимает оба формата. Библиотека @readme/openapi-parser обрабатывает обе версии спецификации, включая OpenAPI 3.1.
• Ввод JSON и YAML: Инструмент сначала пробует JSON.parse, затем переключается на js-yaml для YAML.
• Структурная валидация с точными сообщениями об ошибках: При неудачной валидации сообщения об ошибках парсера разделяются по переносам строк и отображаются индивидуально.
• Предупреждения линтинга: Даже для структурно валидной spec инструмент проверяет три распространённые проблемы качества: отсутствие info.description, операции без description и summary, операции без operationId.
• Счётчики эндпоинтов и операций: После успешной валидации плитки сводки показывают название API, строку версии, общее количество путей и операций.
• Кнопка загрузки примера: Вставляет минимальную, но полную OpenAPI 3.0 spec с единственным GET-эндпоинтом /users.
• История валидации: Предыдущие spec сохраняются в IndexedDB браузера (функция supporter).
• 100% обработка на стороне клиента: Парсер и валидатор работают в браузере.

Как использовать Валидатор OpenAPI

Шаг 1: Вставить Spec

Кликните в текстовую область «OpenAPI Specification (JSON or YAML)» и вставьте содержимое spec. Для YAML включите объявление версии вверху (openapi: "3.0.0" или swagger: "2.0").

Чтобы увидеть инструмент в действии, нажмите кнопку «Load Example» в правом верхнем углу текстовой области.

Шаг 2: Нажать Validate Spec

Нажмите кнопку «Validate Spec» под текстовой областью. Кнопка показывает «Validating...» во время работы парсера.

Шаг 3: Просмотреть результат валидации

Панель результата появляется с одним из двух заголовков:

• «✓ Valid OpenAPI Specification» зелёным — spec прошла структурную валидацию.
• «✗ Validation Failed» красным — spec имеет структурные ошибки.

Шаг 4: Прочитать плитки сводки (валидные Spec)

Для spec, прошедших валидацию, отображаются четыре плитки сводки:

• Title — значение info.title
• Version — значение info.version
• Paths — общее количество записей путей
• Operations — общее количество комбинаций HTTP-метод+путь

Шаг 5: Устранить предупреждения

Три типа предупреждений отображаются даже для валидных spec:

1. Отсутствует info.description — spec не содержит общего описания API.
2. Операции без description или summary — сообщается как количество.
3. Операции без operationId — генераторы SDK используют operationId для именования генерируемых методов.

Практические примеры

Пример 1: Поиск недостающего обязательного поля

✗ Validation Failed
  Could not resolve reference: #/definitions/UserProfile

Пример 2: Валидная Spec с предупреждениями качества

✓ Valid OpenAPI Specification   5 warnings
  info.description: Missing API description — helps users understand the API purpose
  paths.*: 12 operation(s) missing operationId — required for SDK generation

Пример 3: Быстрая проверка большой Spec

После вставки внутренней API spec с 500 путями плитки сводки показывают «Paths: 147» и «Operations: 312».

Советы и лучшие практики

Валидируйте после каждого структурного изменения. Добавление нового пути, изменение $ref или модификация схемы могут ввести ошибки. Валидация занимает менее двух секунд.

Относитесь к предупреждениям operationId как к блокерам для SDK-процессов. Без них генерируемые имена методов будут производиться из путей.

Используйте пример как шаблон. Встроенный пример — это полная, валидная, минимальная OpenAPI 3.0 spec.

Разделяйте структурную валидность и семантическую корректность. Валидатор подтверждает, что spec следует схеме OpenAPI, но не то, что она точно описывает вашу реальную API.

Исправляйте ошибки сверху вниз. Одна недостающая определение схемы может вызвать каскадные ошибки $ref по всей spec.

Распространённые проблемы и устранение неполадок

«Parse error: ...» — ввод не является ни валидным JSON, ни YAML. Частые причины: завершающая запятая в JSON, несогласованный отступ YAML, символ табуляции в отступах YAML.

Валидация не проходит для spec, которую принимает Swagger UI. Swagger UI толерантен к ошибкам. Этот валидатор применяет строгую валидацию по схеме.

Предупреждения появляются даже после добавления описаний. Убедитесь, что добавили description внутри info, а не только на отдельных путях.

Инструмент кажется медленным при первом использовании. Библиотеки загружаются динамически при первом клике валидации.

Конфиденциальность и безопасность

Валидатор OpenAPI обрабатывает вашу spec полностью в браузере. Библиотека @readme/openapi-parser работает локально — никакое содержимое spec не отправляется на внешние сервисы или серверы. Инструмент полностью работает офлайн после загрузки страницы и библиотеки парсера.

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

Валидатор OpenAPI бесплатный? Да. Без стоимости, аккаунта или ограничений использования.

Какие версии OpenAPI поддерживаются? Swagger 2.0, OpenAPI 3.0.x и OpenAPI 3.1.x.

Можно вставить YAML или нужен JSON? Оба формата работают.

Инструмент валидирует реальные API-эндпоинты? Нет. Валидатор проверяет только структурную корректность файла spec.

Почему моя spec не проходит здесь, но работает в Swagger UI? Swagger UI рендерит spec с допуском ошибок. Этот валидатор применяет строгую валидацию по схеме.

Что означает «operationId required for SDK generation»? Генераторы SDK именуют генерируемые методы по значениям operationId. Без них имена конструируются из HTTP-метода и пути.

Есть ли ложные срабатывания в предупреждениях? Три проверки предупреждений консервативны. Проверка info.description срабатывает только при отсутствии или пустоте поля.

Можно валидировать файл spec вместо вставки? Инструмент принимает только вставленный текст — кнопки загрузки файла нет.

Панель истории сохраняет содержимое spec? Да. Сохраняется локально в IndexedDB браузера.

Что произойдёт при вставке пустой spec? Кнопка Validate отключена при пустой текстовой области.

Связанные инструменты

• Скоро: Генератор Mock API — генерируйте mock-данные ответов из валидированной spec для фронтенд-разработки.
• Скоро: Набор для проектирования API — проектируйте и итерируйте структуру API перед экспортом в формат OpenAPI.
• Форматировщик JSON — форматируйте и валидируйте JSON-структуру вашей spec перед вставкой в валидатор.

Попробуйте Валидатор OpenAPI прямо сейчас: Валидатор OpenAPI