Проверка соответствия OpenAPI Обнаружение ошибок в вашем файле Swagger до того, как клиенты будут работать неправильно

Спецификация OpenAPI — это контракт между вашей API и всеми компонентами, которые её используют — автоматически генерирующимися клиентами, мок-серверами, документацией и тестовыми рамками. Проблема в том, что в отличие от прикладного кода, при нарушении спецификации не возникает исключения. Ошибки проявляются тихо и приводят к неправильным результатам в дальнейшем, и первое, что вы узнаете об этом, — это когда клиентский SDK генерирует неприемлемый код или документация отображается с отсутствующими эндпоинтами.

Раннее обнаружение ошибок спецификации — до того, как они достигнут потребителей — является задачей проверки спецификации. В этой статье рассматриваются те элементы, которые нужно проверять, где скрываются распространённые ошибки и как проводить проверку локально и в браузере.

Почему формат вашей спецификации важен за пределами документации

Большинство разработчиков рассматривают спецификацию OpenAPI как документационный артефакт — что обеспечивает работу Swagger UI или Redoc. Это лишь половина картины. Спецификация также является источником истины для:

• генерации кода — Инструменты, такие как openapi-generator и swagger-codegen, генерируют серверские шаблоны и клиентские библиотеки напрямую из спецификации. Неправильная схема приводит к неправильному коду.
• контрактных тестов — Фреймворки, такие как Dredd и Schemathesis, проверяют вашу живую API на соответствие спецификации. Невалидная спецификация приводит к тому, что тесты либо не запускаются, либо генерируют ложные результаты.
• мок-серверов — Инструменты, такие как Prism и подобные, предоставляют мок-ответы на основе значений и схем спецификации. Неправильные схемы приводят к неправильным мок-ответам.
• настройки гейтвейсов — AWS API Gateway, Kong и другие могут импортировать спецификации OpenAPI для настройки маршрутизации, аутентификации и валидации. Невалидная спецификация тихо пропускает или неправильно настраивает маршруты.

Никакие из этих инструментов не сообщат вам, что спецификация неверна, в понятной форме. Они либо аварийно останавливаются, генерируют мусор, либо тихо пропускают затронутые части. Проверка спецификации до того, как она достигнет этих потребителей, является неприменимой.

OpenAPI 2.0 против 3.0 против 3.1: Различия версий, которые ловят разработчиков

Версия, указанная в начале вашей спецификации, определяет применимые правила — и многие ошибки возникают из-за неправильного использования конвенций между версиями.

• OpenAPI 2.0 (Swagger) — Использует swagger: "2.0". Тела запросов идут в parameters с in: body. Определения находятся в definitions, а не components/schemas. Нет поддержки oneOf, anyOf, или not на уровне схемы.
• OpenAPI 3.0.x — Использует openapi: "3.0.x". Тела запросов перемещаются в requestBody. Схемы объединяются под components. Поддерживает oneOf, anyOf, allOfи not. Добавляет links и callbacks.
• OpenAPI 3.1.0 — Полностью согласуется с JSON Schema draft 2020-12. nullable заменяется на type: [string, null]. exclusiveMinimum/exclusiveMaximum изменение из логических значений на числовые. $schema теперь разрешены в схемах.

Наиболее распространённая ошибка миграции: копирование спецификации 2.0 и изменение поля версии на 3.0.0 без перемещения тел запросов из parameters к requestBody. Спецификация выглядит валидной как JSON/YAML, но не проходит семантическую проверку.

Распространённые ошибки спецификации и места, где они скрываются

Ошибки спецификации подчиняются предсказуемым паттернам. Ниже приведены наиболее часто встречающиеся в реальных кодовых базах:

Отсутствующие обязательные поля

Каждая операция должна иметь хотя бы один ответ с кодом 2xx. Каждый параметр должен иметь name и значение in . Параметры в URL (например, /users/{id}) должны иметь соответствующий объект параметра с in: path и required: true. Отсутствие любого из этих элементов приводит к спецификации, которая технически может быть разобрана, но нарушает валидаторы и генераторы кода.

Невалидные пути $ref

А $ref которые указывают на несуществующий компонент — одна из самых распространённых ошибок спецификации. Ссылка выглядит корректно — $ref: "#/components/schemas/UserProfile" — но целевая схема была переименована или удалена. Парсеры JSON/YAML принимают это без возражений. Только спецификационный валидатор может обнаружить это.

Внешние $ref пути ещё опаснее — они указывают на другие файлы или URL, которые могут быть недоступны в каждом окружении. Вставляйте эти ссылки в спецификацию до того, как она будет распространяться или использоваться с инструментами, не разрешающими внешние ссылки.

Неправильные типы схем

Несоответствия типов схем являются тонкими. Указание type: integer на поле, возвращающее значения типа float. Использование format: date-time с полем, возвращающим Unix-временные метки (целые числа). Определение enum с значениями, не соответствующими объявленному type. Эти ошибки проходят парсинг YAML, но приводят к неправильным свойствам в генерируемых клиентах.

Циклические ссылки

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

Структурные и семантические ошибки

Ошибки валидации не являются одинаковыми. Понимание различий помогает вам приоритизировать исправления:

• Структурные ошибки — Спецификация не соответствует схеме OpenAPI. Отсутствуют обязательные поля, неправильные имена свойств или типы не соответствуют формату спецификации. Эти ошибки обнаруживаются строгими схемами валидации и блокируют большинство инструментов.
• Семантические ошибки — Спецификация структурно корректна и проходит валидацию схемы, но описывает что-то, что не может работать. Например, эндпоинт с параметром в URL, но без определения параметра. Схема ответа использует allOf с конфликтующими обязательными полями. Эти ошибки обнаруживаются более глубокими правилами линтинга, а не базовыми проверками схемы.

Большинство онлайн-валидаторов и базовых CLI-инструментов обнаруживают структурные ошибки. Обнаружение семантических ошибок требует правилового линтера, такого как Spectral, который оценивает внутреннюю логику и согласованность спецификации.

components/schemas: ДRY определения против встроенных схем

OpenAPI 3.0 ввёл components/schemas как основное место для определения повторно используемых схем. Стоимость:

• Общие схемы в компонентах — Правильно, когда одна и та же схема встречается в нескольких местах (например, объект, возвращаемый несколькими эндпоинтами). Использование User сохраняет спецификацию DRY и генерирует один названный класс в клиентских SDK. $ref: "#/components/schemas/User" Встроенные схемы
• — Правильно для одноразовых форматов ответов, специфичных для одного эндпоинта и не планирующих повторного использования. Встраивание избегает загрязнения одноразовыми определениями, которые делают спецификацию трудной для чтения. components/schemas Неправильный паттерн — определение схемы в

и последующее её игнорирование. Валидаторы, такие как Spectral, могут выявить неприменённые компоненты, что часто указывает на components/schemas который был намерен ссылаться на неё, но указывает куда-то иное. $ref Запросы тела и параметры: где возникают ошибки

В OpenAPI 3.0 запросы тел и параметры строго разделяются:

параметры

• — Для значений в пути, запросе, заголовке и куках. Каждый параметр — это скалярное значение, а не сложный объект. тело запроса
• — Для тела запроса (JSON-тело, форматные данные, загрузка файлов). Обязательно для операций POST/PUT/PATCH, которые принимают тело. Ошибки, которые ловят разработчиков при миграции с 2.0: в Swagger 2.0 тела запросов были параметрами с

. В OpenAPI 3.0 это недопустимо — in: bodyне существует. Спецификация с in: body проходит парсинг YAML, но не проходит валидацию спецификации, и генераторы кода либо выдают ошибку, либо тихо игнорируют тело запроса. in: body Как проводить локальную проверку спецификации

Три надёжных CLI-инструмента для локальной проверки, от простейшего до наиболее полного:

swagger-cli

Быстрая структурная проверка и

распознавание. Хорошо подходит для быстрого проверки: $ref Отчёт о структурных ошибках и повреждённых

npm install -g @apidevtools/swagger-cli
swagger-cli validate openapi.yaml

путях. Не обнаруживает семантические проблемы или проблемы оформления. $ref Redocly CLI

Структурная проверка плюс настраиваемый набор правил. Хорошее значение строгости для производственных спецификаций:

Обнаруживает отсутствующие описания, повреждённые ссылки и многие семантические проблемы по умолчанию.

npm install -g @redocly/cli
redocly lint openapi.yaml

Spectral

Наиболее настраиваемый линтер. Запускает встроенный набор правил OpenAPI плюс пользовательские правила, которые вы определяете. Идеально подходит для команд, которые хотят обеспечить внутренние стили API:

Spectral различает ошибки (прекращающие работу спецификации) и предупреждения (проблемы оформления или полноты), поэтому вы можете сначала исправить критические проблемы, не подвергаясь шуму от рекомендаций.

npm install -g @stoplight/spectral-cli
spectral lint openapi.yaml

Проверка спецификации в браузере без установки ничего

Если вы хотите быстро проверить спецификацию — без установки CLI или запуска сборки — инструмент

OpenAPI / Swagger Spec Validator на iotools.cloud работает полностью в браузере. Вставьте вашу спецификацию YAML или JSON и он отчёт о структурных ошибках, повреждённых путях, отсутствующих обязательных полях и проблемах, связанных с версиями OpenAPI 2.0, 3.0 и 3.1. $ref Он полезен для быстрой проверки перед коммитом, для проверки спецификации, которую кто-то другой отправил, или для проверки спецификации, сгенерированной из аннотаций, перед запуском генерации кода.

Интеграция проверки спецификации в рабочий процесс

Одноразовая проверка выявляет немедленные проблемы, но не предотвращает регрессии. Более устойчивый подход:

Предварительный коммит

• — Запуск до каждого коммита. Невалидная спецификация никогда не достигает репозитория. swagger-cli validate или spectral lint Шаг в CI-процессе
• — Добавьте проверку спецификации на раннем этапе CI-процесса, до любых шагов генерации кода или развертывания, которые зависят от спецификации. Проверка генерированной спецификации
• — Если вы генерируете спецификацию из аннотаций кода (например, springdoc, swagger-annotations, FastAPI), проверяйте выход генерации, а не только аннотации. Сам процесс генерации может создавать невалидный выход при конфликтах или неполных аннотациях. Цель — сделать невозможным отправку невалидной спецификации — а не просто исправлять её, когда потребитель сообщает о проблемах.

Проверка соответствия OpenAPI: обнаружение ошибок в вашем файле Swagger до того, как клиенты сломаются 2

Вам также может понравиться