Валидатор OpenAPI JSON

Частые ошибки JSON, из-за которых проверка не проходит

JSON строже YAML, поэтому большинство сбоев в вручную редактируемом файле вызвано синтаксисом, а не архитектурой API. Обычные причины: запятая после последнего свойства, одинарные кавычки вместо двойных, комментарий (JSON их не допускает) или пропущенная закрывающая фигурная скобка после длинного объекта paths. Повреждённый файл обычно завершается сообщением “Could not parse as JSON or YAML” или отсутствием полей, потому что ничего пригодного прочитать не удалось.

Если вы видите только ошибку разбора, сначала найдите синтаксическую ошибку. Структурные проверки запускаются, когда документ читается как объект.

Пример

Возьмём небольшой документ:

{
  "openapi": "3.0.3",
  "info": { "title": "Orders API" },
  "paths": {
    "orders": { "get": { "summary": "List orders" } }
  }
}

Он разбирается, поле openapi и объект paths присутствуют. Отчёт всё равно покажет:

Из-за одной ошибки документ не считается валидным. Добавьте "version": "1.0.0" в info и переименуйте ключ в /orders. Повторный запуск уберёт оба замечания.

Что значит успешная проверка, а что нет

Чистый отчёт означает, что каркас правильный. Он не переходит по ссылкам $ref, не проверяет схемы и не подтверждает, что у каждой операции есть ответы. Считайте его быстрым фильтром перед фиксацией файла, а глубокие правила проверяйте полноценным линтером.

Практический порядок работы с JSON-спецификациями

Храните спецификацию в системе контроля версий и вставляйте её сюда перед каждым коммитом, который меняет paths. Поскольку проверка быстрая, она работает как проверка здравого смысла после слияния изменений нескольких человек, когда повторяющиеся ключи или неверно поставленная скобка наиболее вероятны. Если JSON генерируется скриптом сборки, вставляйте сгенерированный результат, а не шаблон, чтобы проверить то, что получат читатели. Когда отчёт чистый, файл можно публиковать или передавать генератору документации с большей уверенностью, что верхний уровень структуры корректен.