Как проверить спецификацию OpenAPI

Что проверяется в редакторе OpenAPI: синтаксис YAML и JSON, повторяющиеся ключи, ссылки $ref, отрисовка в Swagger UI — и как получить ревью дизайна API.

Спецификация может быть синтаксически верной, но с битой ссылкой, пропущенной схемой ответа или неудачными именами. Проверку удобно вести в несколько слоёв — от синтаксиса к дизайну.

1. Синтаксис

Откройте спецификацию в редакторе OpenAPI. Ошибки YAML или JSON подсвечиваются по мере ввода, список с номерами строк — под редактором. Отдельно ловятся повторяющиеся ключи: два одинаковых пути или два ответа 200 в одном методе многие парсеры молча склеивают, а редактор считает ошибкой.

Ошибка в спецификации OpenAPI подсвечена в строке — Ошибки синтаксиса и повторяющиеся ключи — в строках кода

2. Это вообще OpenAPI?

Если в документе нет поля openapi (или swagger для версии 2.0), над документацией появится предупреждение. Так обычно выглядят фрагменты, скопированные из большой спецификации без шапки.

3. Ссылки и структура — по документации

Swagger UI справа строится по спецификации целиком, поэтому проблемы структуры видны в нём:

битая ссылка $ref — ошибка разрешения ссылки в документации;
метод без ответов, схема без типа, пустые теги — сразу заметны при просмотре;
ссылки на другие файлы проекта разрешаются по папкам, Ctrl+клик по $ref открывает целевой файл — так быстро проверить, что он существует.

4. Схемы данных — на примерах

Чтобы проверить, что схемы пропускают нужные данные, преобразуйте их в JSON Schema (гайд) и проверьте примеры запросов и ответов на вкладке «Проверка» редактора JSON Schema.

5. Дизайн API — ИИ-ревью

Соответствие спецификации лучшим практикам (именование, коды ответов, пагинация, описание ошибок, безопасность) смотрит ИИ-ревью — кнопка в панели редактора, тарифы «Макс» и выше. Замечания привязаны к строкам, полный отчёт можно скачать в PDF.

Автоматическая проверка в CI

Если спецификации хранятся в проекте, проверку синтаксиса можно вызвать из CI через внешний API или MCP — см. гайд «ИИ-агент и MCP» и документацию API.

Чек-лист перед публикацией спецификации

Нет ошибок синтаксиса и повторяющихся ключей.
У каждого метода есть operationId, summary и хотя бы один успешный ответ со схемой.
Ошибки описаны: 400, 401/403, 404, 409 — с единой схемой тела ошибки.
Все $ref разрешаются — в документации справа нет ошибок разрешения ссылок.
Идентификаторы и даты имеют форматы (uuid, date-time), перечисления — enum.
В servers — реальные адреса окружений.
Схемы безопасности описаны и применены (security).

Вопросы и ответы

Проверяет ли редактор спецификацию по официальной схеме OpenAPI? Редактор проверяет синтаксис, ключи и распознаёт тип документа, а структуру видно по документации Swagger UI. Глубокую проверку дизайна делает ИИ-ревью.

Как проверить, что ответы сервиса соответствуют спецификации? Преобразуйте схемы в JSON Schema и проверьте реальные ответы на вкладке «Проверка» редактора JSON Schema.