Автоматический анализ OpenAPI/Swagger спецификаций

Каждый, кто хоть раз работал с документацией API в Confluence, знает эту боль: километровые страницы на каждый метод — с описанием всего и вся в виде текста, таблиц, диаграмм последовательности. Такая документация устаревает ровно в тот момент, как её закончили писать. После передачи задачи в разработку, как только что-то непонятно, все идут к аналитику: «А как это работает? А что это значит?»

Ответ на этот вызов — OpenAPI. Это открытый стандарт для машиночитаемого описания HTTP API, который позволяет создавать единый источник правды о вашем API: понятный и людям, и компьютерам. До середины 2010-х годов каждый разработчик самостоятельно определял, как документировать свои API. Это приводило к огромному количеству ошибок и трате времени. Решение пришло в 2010 году с началом разработки Swagger, а в 2015 году спецификация была передана организации OpenAPI Initiative и получила название OpenAPI.

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

Часто термины Swagger и OpenAPI используются как синонимы, но это не совсем правильно. Если простыми словами описать различия:

- Swagger — это коммерческий продукт и спецификация версии 2.0, набор инструментов для работы с API.

- OpenAPI — это бесплатная спецификация Swagger версии 3.0 и выше.

Swagger было первичным оригинальным названием OpenAPI. Сегодня Swagger — это экосистема инструментов, которая позволяет автоматически описывать API на основе его кода или набора правил. А OpenAPI — это сам стандарт описания.

Основные инструменты экосистемы Swagger:

- Swagger Editor — онлайн-редактор для написания и проверки спецификаций

- Swagger UI — интерактивная документация, позволяющая отправлять запросы прямо из браузера

- Swagger Codegen — генератор кода клиента и сервера на основе спецификации

OpenAPI сегодня — это универсальный интерфейс для взаимодействия клиентов с сервисами, не зависящий от языков программирования.

Спецификация OpenAPI описывает ресурсы REST-приложения, маршруты обращения к ним, используемые HTTP-методы, а также структуры данных полезной нагрузки запросов и ответов.

Ключевые преимущества:

1. Стандартизация. Понятный всем стандарт документирования. Разработчики, тестировщики и аналитики разных команд одинаково понимают описание API.

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

3. Параллельная разработка. Спроектировав заранее контракт API, команды тестирования, разработки клиента и сервера могут работать параллельно.

4. Автоматическое тестирование. На основе спецификации можно сгенерировать API-тесты.

5. Кодогенерация. Из готовой спецификации можно сгенерировать клиент, сервер, документацию и тесты.

Спецификация описывается в формате JSON или YAML и представляет собой файл (или несколько — для больших проектов). Рассмотрим основные секции:

1. openapi — версия спецификации

Первая и обязательная секция с версией спецификации, по которой инструменты проверяют совместимость.

2. info — метаданные API

Своего рода «паспорт» документа. Включает:

- title — название API

- description — описание

- version — версия API

Для публичных или партнёрских API рекомендуется подробно заполнять поле description.

3. servers — список серверов

Адреса, на которые направляются запросы. Разделены по назначению: тестовый, рабочий и т.д.

4. paths — доступные эндпоинты и методы

Сердце спецификации. Описывает маршруты (paths) с указанием HTTP-методов доступа к ним (GET, POST, PUT, DELETE и др.), а также содержимое заголовков и тела запросов (requestBody) и ответов (responses).

5. components — переиспользуемые компоненты

Включает объекты, которые используются в разных частях спецификации:

- schemas — схемы данных (JSON Schema) для описания структур

- parameters — параметры запросов

- responses — ответы

- securitySchemes — схемы аутентификации

- requestBodies — тела запросов

6. tags — группировка энд поинтов

Облегчает навигацию по большим API. Операции можно сгруппировать по типу: users, payments и т.д.

Полная спецификация также может включать секции webhooks (вебхуки) и security (требования авторизации).

Существует два основных подхода к созданию OpenAPI-спецификаций.

Design-First (Spec-First) — сначала спецификация

При этом подходе сначала разрабатывается спецификация — проектируется набор конечных точек и передаваемые данные. Только после этого пишется код.

Преимущества Design-First:

- Согласованный контракт до разработки — ошибки выявляются на этапе проектирования

- Параллельная работа команд

- Документация создается до кода, а не после

- Упрощается создание тест-кейсов

Code-First — сначала код

Спецификация OpenAPI генерируется из исходного кода, например, с помощью фреймворка FastAPI.

Преимущества Code-First:

- В сгенерированной спецификации меньше синтаксических ошибок

- Не требует отдельного этапа проектирования

Какой подход выбрать?

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

Специализированные редакторы, например Swagger Editor или SwaggerHub, проверяют синтаксические ошибки в YAML-файле, компилируя документацию для визуального просмотра в SwaggerUI. Однако семантические ошибки редактор не проверяет — а именно их чаще всего совершают аналитики.

Типичные ошибки в спецификации OpenAPI

Аналитики при разработке спецификации OpenAPI допускают характерные ошибки:

1. Передача конфиденциальных данных в параметрах маршрута — например, в `/route/{param}` или в строке GET-запроса

2. Отсутствие аутентификации в запросах

3. Неправильное использование HTTP-методов — например, использование POST вместо GET для получения данных

4. Отсутствие обязательных полей в схемах запросов и ответов

5. Несоответствие типов данных — например, указание string вместо integer

6. Отсутствие примеров (example) для полей, что затрудняет понимание API

Инструменты для автоматического тестирования по OpenAPI

Portman — один из самых мощных инструментов для тестирования API по спецификации OpenAPI. Это «комбайн», который позволяет:

- Сконвертировать спецификацию OpenAPI в коллекцию Postman

- Добавить контрактные, вариационные и интеграционные тесты

- Заполнить параметры запросов случайными или фиксированными данными

- Запустить тестирование через Newman

- Интегрировать всё в CI/CD

Встроенные контрактные тесты Portman:

- statusSuccess — проверяет, что ответ вернул код 2xx

- statusCode — проверяет конкретный код ответа

- responseTime — проверяет время выполнения

- contentType — проверяет соответствие заголовка Content-Type

- jsonBody — проверяет, что тело ответа в формате JSON

- schemaValidation — проверяет, что тело ответа соответствует JSON-схеме из спецификации

- headersPresent — проверяет наличие заголовков

Portman написан на Node.js и устанавливается через npm:

```bash
npm install -g newman @apideck/portman
```

Автоматическая генерация тестов

На основе спецификации OpenAPI можно генерировать API-тесты, что позволяет автоматизировать большую работу в рамках всего проекта и уменьшить объем рутинного кода.

Спецификация API упрощает QA-специалистам создание тест-кейсов, что обеспечивает общее более высокое качество ПО.

OpenAPI в CI/CD: непрерывная проверка контрактов

Одно из главных преимуществ OpenAPI — возможность интеграции в контур CI/CD. Это позволяет:

1. Автоматически проверять каждое изменение спецификации на соответствие стандартам

2. Генерировать тесты при каждом коммите

3. Выявлять breaking changes до того, как они попадут в продакшен

4. Автоматически обновлять документацию при изменении API

Такой подход гарантирует, что документация всегда актуальна, а контракты API проверяются автоматически на каждом этапе разработки.

Шаг 1. Выберите подход

Определитесь, будете ли вы использовать Design-First (сначала спецификация) или Code-First (сначала код). Для крупных проектов с несколькими командами рекомендуется Design-First.

Шаг 2. Изучите структуру

Ознакомьтесь с основными секциями спецификации: openapi, info, servers, paths, components.

Шаг 3. Используйте редактор

Начните с Swagger Editor (editor.swagger.io) — бесплатного онлайн-редактора с подсветкой синтаксиса и визуальным просмотром.

Шаг 4. Опишите первый эндпоинт

Начните с простого GET-запроса, постепенно добавляя параметры, тело запроса и ответы.

Шаг 5. Настройте автоматическую проверку

Внедрите Portman или аналогичный инструмент для автоматического тестирования контрактов.

Шаг 6. Интегрируйте в CI/CD

Подключите проверку спецификации и генерацию тестов в ваш пайплайн разработки.

OpenAPI — это не просто формат документации, это фундамент для автоматизации разработки API. Он позволяет создавать единый источник правды о вашем API, который одновременно служит:

- Документацией для разработчиков и аналитиков

- Контрактом для команд разработки

- Основой для автоматического тестирования

- Источником для генерации кода

Ключевые выводы:

1. OpenAPI — это открытый стандарт для машиночитаемого описания HTTP API. Swagger — экосистема инструментов для работы с этим стандартом.

2. Спецификация структурирована и включает info, servers, paths, components и другие секции.

3. Design-First подход (сначала спецификация) позволяет выявлять ошибки на этапе проектирования и ускоряет разработку.

4. Синтаксические ошибки проверяются редакторами, но семантические ошибки требуют внимания аналитика.

5. Portman и аналогичные инструменты позволяют автоматически тестировать API на соответствие спецификации.

6. Интеграция в CI/CD обеспечивает непрерывную проверку контрактов и актуальность документации.

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